CodeProject: CIni. Free source code and programming help

Announcements

	Windows 7 Comp Win a laptop!
	Monthly Competition

Articles

Desktop Development

Web Development

Enterprise Systems

Content Management Server

Microsoft BizTalk Server

SQL Reporting Services

Platforms, Frameworks & Libraries

Windows Communication Foundation

Windows Presentation Foundation

Windows Workflow Foundation

Cryptography & Security

Threads, Processes & IPC

WinHelp / HTMLHelp

Uncategorised Quick Answers

Graphics / Design

Expression

Usability

Development Lifecycle

Debug Tips

Design and Architecture

Uncategorised Technical Blogs

Services

Code-signing Certificates

Job Board

CodeProject VS2008 Addin

Feature Zones

Product Showcase

Code Signing Resources

WhitePapers / Webcasts

ASP.NET Web Hosting

Advanced Search
Add to IE Search

Discuss

Report

52 votes for this article.

Popularity: 7.92 Rating: 4.62 out of 5

Sample Image - CIni_Demo.gif

Introduction
What INI Files Are
Why Another Class
What Do We Get
How to Use
Class Interface
Method Description
History

Introduction

While it is recommended that programmers should use system registry to store application initialization data, I found myself still using INI files often. I'm not going to discuss or compare the pro's and con's of registry and INI file in detail, but one main reason I use INI files is that, I believe an application should "infect" the system as little as possible, if it could be done by using an INI file, I will not use the registry.

Back to | Table of Contents|

What INI Files Are

"INI files" are text files which store application initialization (hence "ini") data, they are usually tiny in size and consist of "sections", "keys" and "values". A normal INI file will look like this:

[Settings]
User=John Smith
Age=25
Family=John Smith,Alice Smith,Tommy,Mike
Has car=1
Has truck=0

[Computer]
IP=69.202.5.38
User=Howard Mark

In the above sample, there are two sections called "Settings" and "Computer". Under section "Settings", there are five "key pairs", that is, "Key" and "Value" concatenated by a "=" sign. The first key of section "Settings" is "User", whose value is "John Smith", the second key of section "Settings" is "Age", whose value is "25", and so on.

In an INI file, there should be no sections with the same name, and in one section there should be no keys with the same name. Keys in different sections may have the same name, for example, both section "Settings" and "Computer" have key "User", but that is OK since they belong to different sections.

Sections and keys are case-insensitive.

Back to | Table of Contents |

Why Another Class

I'm aware of that there are quite some INI file handling classes out there on the Internet already, so why should I make another one? Well, first of all, I believe that most of such classes are not as "comprehensive" as this one is, they provide access to strings, integers, maybe doubles, and that's pretty much it, while in this class, you will see a huge change.

Second, some other classes used to load the whole file into memory, then access that in-memory copy only, this would cause problems if there are other applications that are accessing the same INI file simultaneously because if other application changes the INI file contents, your application would not know since your are only manipulating your own copy. My class uses Win32 API to access INI files, so every read & write operation will get the most recent result.

This class does not require MFC, but if MFC is already linked in your project, you can use some "MFC-only" methods provided by this class for more convenience, we all know how much handier CStringArray is than TCHAR**, right?

This class is UNICODE compliant.

Back to | Table of Contents|

What Do We Get

CIni, is a Win32 API wrapping class that is specialized in ini file handling, it provides access to not only primitive data types, but also structs such as POINT and RECT, and even user defined structs.

Also, this class implements some commonly needed (at least by myself) methods, for example, AppendString, IncreaseInt, InvertBool, GetArray, etc, these methods are quite self-explained by their names, but if you don't know what they do exactly, there will be detailed description later.

Sections & keys access are implemented too in this class, you can check, list, copy, delete, move sections & keys in one single line of code.

Back to | Table of Contents |

How to Use

To use the CIni class in your project, simply add "Ini.cpp" into your workspace and include "Ini.h" where needed.

Back to | Table of Contents|

Class Interface

Method Description

CIni::CIni()

CIni::CIni(LPCTSTR lpPathName)

Parameters

lpPathName

A null-terminated string which specifies the INI file path.

Remarks

Constructs a CIni object.

Back to | Table of Contents |Class Interface|

void CIni::SetPathName(LPCTSTR lpPathName)

Parameters

lpPathName

A null-terminated string which specifies the INI file path.

Remarks

Specify the INI file path.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetPathName(LPTSTR lpBuffer, DWORD dwBufSize) const

CString CIni::GetPathName() const

Return Value

DWORD - Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

CString - A CString object contains the string.

Parameters

lpBuffer

Points to the buffer that is to receive the copied string. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the INI file path.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

Remarks

Retrieves the INI file path.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetString(LPCTSTR lpSection, LPCTSTR lpKey, LPTSTR lpBuffer, DWORD dwBufSize, LPCTSTR lpDefault = NULL) const

CString CIni::GetString(LPCTSTR lpSection, LPCTSTR lpKey, LPCTSTR lpDefault = NULL) const

Return Value

DWORD - Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

CString - A CString object contains the string.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpBuffer

Points to the buffer that is to receive the copied string. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the target string value.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

lpDefault

A null-terminated string specifies the default string value to retrieve if the specified section or key does not exist in the INI file. If this parameter is NULL, an empty string will be used instead.

Remarks

Retrieves a string value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteString(LPCTSTR lpSection, LPCTSTR lpKey, LPCTSTR lpValue) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpValue

A null-terminated string to be written to the INI file.

Remarks

Writes a string to the the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::AppendString(LPCTSTR lpSection, LPCTSTR lpKey, LPCTSTR lpString) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpString

A null-terminated string to be appended to an existing key value in the INI file.

Remarks

Append a string to an existing key value in the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetArray(LPCTSTR lpSection, LPCTSTR lpKey, LPTSTR lpBuffer, DWORD dwBufSize, LPCTSTR lpDelimiter = NULL, BOOL bTrimString = TRUE) const

void CIni::GetArray(LPCTSTR lpSection, LPCTSTR lpKey, CStringArray *pArray, LPCTSTR lpDelimiter = NULL, BOOL bTrimString = TRUE) const

Return Value

Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpBuffer

Points to the buffer that is to receive the copied string. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the target string value. String copied into lpBuffer is in "double-null terminated" format which can be parsed using CIni::ParseDNTString.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

lpDelimiter

A null-terminated string specifies the delimiter used to separate the string. If this parameter is NULL, the default delimiter _T(",") will be used. If this parameter is empty, the string is not separated.

bTrimString

If this parameter is non-zero, leading and trailing white spaces are trimmed from each sub-string.

pArray

Pointer to an MFC CStringArray to receive the string array.

Remarks

Retrieves a string value from the INI file and parses it as an array using the specified delimiter.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteArray(LPCTSTR lpSection, LPCTSTR lpKey, const CStringArray *pArray, int nWriteCount = -1, LPCTSTR lpDelimiter = NULL) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

pArray

Pointer to an MFC CStringArray which stores the string array to be written to the INI file.

nWriteCount

Specifies the maximum number of strings to write. If this parameter is -1, all strings stored in *pArray will be written to the INI file.

lpDelimiter

A null-terminated string specifies the delimiter that will be used to separate the string. If this parameter is NULL, the default delimiter _T(",") will be used. If this parameter is empty, the string is not separated.

Remarks

Writes an array of strings to the INI file. If the specified section or key does not exist, they are created. This function is only available if _AFXDLL is defined.

Back to | Table of Contents | Class Interface |

int CIni::GetInt(LPCTSTR lpSection, LPCTSTR lpKey, int nDefault, int nBase = BASE_DECIMAL) const

Return Value

The int value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Retrieves an int value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteInt(LPCTSTR lpSection, LPCTSTR lpKey, int nValue, int nBase = BASE_DECIMAL) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nValue

Specifies the int value to be written to the INI file.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Writes an int value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::IncreaseInt(LPCTSTR lpSection, LPCTSTR lpKey, int nIncreaseBy = 1, int nBase = BASE_DECIMAL) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nIncreaseBy

Specifies the int value to increase.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Retrieves an int value from the INI file, increase it by nIncreaseBy, then write the result int value back to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

UINT CIni::GetUInt(LPCTSTR lpSection, LPCTSTR lpKey, UINT nDefault, int nBase = BASE_DECIMAL) const

Return Value

The UINT value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Retrieves an UINT value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteUInt(LPCTSTR lpSection, LPCTSTR lpKey, UINT nValue, int nBase = BASE_DECIMAL) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nValue

Specifies the UINT value to be written to the INI file.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Writes an UINT value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::IncreaseUInt(LPCTSTR lpSection, LPCTSTR lpKey, UINT nIncreaseBy = 1, int nBase = BASE_DECIMAL) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

nIncreaseBy

Specifies the UINT value to increase.

nBase

Specifies the integer base used to preprocess the value. This parameter may be BASE_BINARY, BASE_OCTAL, BASE_DECIMAL or BASE_HEXADECIMAL.

Remarks

Retrieves an UINT value from the INI file, increase it by nIncreaseBy, then write the result UINT value back to the INI file. If the specified section or key do not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::GetBool(LPCTSTR lpSection, LPCTSTR lpKey, BOOL bDefault) const

Return Value

The BOOL value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

bDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

Remarks

Retrieves a BOOL value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteBool(LPCTSTR lpSection, LPCTSTR lpKey, BOOL bValue) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

bValue

Specifies the BOOL value to be written to the INI file.

Remarks

Writes a BOOL value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::InvertBool(LPCTSTR lpSection, LPCTSTR lpKey) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

Remarks

Retrieves a BOOL value from the INI file, inverts it, then writes the inverted BOOL value back to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

TCHAR CIni::GetChar(LPCTSTR lpSection, LPCTSTR lpKey, TCHAR cDefault) const

Return Value

The TCHAR value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

cDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

Remarks

Retrieves a TCHAR value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteChar(LPCTSTR lpSection, LPCTSTR lpKey, TCHAR cValue) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

cValue

Specifies the TCHAR value to be written to the INI file.

Remarks

Writes a TCHAR value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

double CIni::GetDouble(LPCTSTR lpSection, LPCTSTR lpKey, double fDefault) const

Return Value

The double value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

fDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

Remarks

Retrieves a double value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteDouble(LPCTSTR lpSection, LPCTSTR lpKey, double fValue, int nPrecision = -1) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

fValue

Specifies the double value to be written to the INI file.

nPrecision

Specifies the precision used when the double value is written to the INI file. If this parameter is smaller than 0, precision is determined automatically.

Remarks

Writes a double value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::IncreaseDouble(LPCTSTR lpSection, LPCTSTR lpKey, double fIncreaseBy, int nPrecision = -1) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

fIncreaseBy

Specifies the double value to increase.

nPrecision

Specifies the precision used when the double value is written to the INI file. If this parameter is smaller than 0, precision is determined automatically.

Remarks

Retrieves a double value from the INI file, increase it by fIncreaseBy, then write the result double value back to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

POINT CIni::GetPoint(LPCTSTR lpSection, LPCTSTR lpKey, POINT ptDefault) const

Return Value

A POINT value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

ptDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

Remarks

Retrieves a POINT value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WritePoint(LPCTSTR lpSection, LPCTSTR lpKey, POINT pt) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

pt

Specifies the POINT value to be written to the INI file.

Remarks

Writes a POINT value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

RECT CIni::GetRect(LPCTSTR lpSection, LPCTSTR lpKey, RECT rcDefault) const

Return Value

A RECT value retrieved from the INI file.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

rcDefault

Specifies the default value to retrieve if the specified section or key does not exist in the INI file.

Remarks

Retrieves a RECT value from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteRect(LPCTSTR lpSection, LPCTSTR lpKey, RECT rc) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

rc

Specifies the RECT value to be written to the INI file.

Remarks

Writes a RECT value to the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetDataBlock(LPCTSTR lpSection, LPCTSTR lpKey, LPVOID lpBuffer, DWORD dwBufSize, DWORD dwOffset = 0) const

Return Value

Specifies the length, in bytes, of the copied data block.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpBuffer

Pointer to a buffer that receives the data to copy. If this parameter is NULL, the return value will be the actual length, in bytes, of the target data.

dwDataSize

Specifies the size, in bytes, of the buffer pointed to by the lpbuffer parameter.

dwOffset

Specifies the offset from which the source data is started to be read.

Remarks

Retrieves a block of data from the INI file.

Example

// To retrieve 5 RECT's from the ini file

CIni ini(_T("c:\\test.ini"));
RECT data[5];
DWORD dwCopied = ini.GetDataBlock(_T("sect1"), _T("rect array"), 
                                 (LPVOID)data, sizeof(RECT) * 5);

Back to | Table of Contents | Class Interface |

BOOL CIni::WriteDataBlock(LPCTSTR lpSection, LPCTSTR lpKey, LPCVOID lpData, DWORD dwDataSize) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpData

Pointer to a buffer that contains the data to be written to the INI file. If this parameter is NULL, the function fails.

dwDataSize

Specifies the size, in bytes, of the buffer pointed to by the lpData parameter.

Remarks

Writes a block of data to the INI file. If the specified section or key does not exist, they are created.

Example

// To write 3 int's to the ini file

CIni ini(_T("c:\\test.ini"));
int data[3] = { 202, -126, 6500 }; // Just a sample

DWORD dwCopied = ini.WriteDataBlock(_T("sect1"), 
   _T("int array"), (LPCVOID)data, sizeof(int) * 3);

Back to | Table of Contents | Class Interface |

BOOL CIni::AppendDataBlock(LPCTSTR lpSection, LPCTSTR lpKey, LPCVOID lpData, DWORD dwDataSize) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

lpData

Pointer to a buffer that contains the data to append to the INI file. If this parameter is NULL, the function fails.

dwDataSize

Specifies the size, in bytes, of the buffer pointed to by the lpData parameter.

Remarks

Append a block of data to a specified key in the INI file. If the specified section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::IsSectionExist(LPCTSTR lpSection) const

Return Value

Returns non-zero if the section specified by lpSection exists in the INI file, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

Remarks

Checks for whether the specified section exists in the INI file.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetSectionNames(LPTSTR lpBuffer, DWORD dwBufSize) const

void CIni::GetSectionNames(CStringArray *pArray) const

Return Value

Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

Parameters

lpBuffer

Points to the buffer that is to receive the copied section name list. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the section name list. String copied into lpBuffer is in "double-null terminated" format which can be parsed using CIni::ParseDNTString.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

pArray

Pointer to an MFC CStringArray object to receive the section name list.

Remarks

Retrieves a list of section names from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::CopySection(LPCTSTR lpSrcSection, LPCTSTR lpDestSection, BOOL bFailIfExist) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSrcSection

A null-terminated string specifies the source section name in the INI file.

lpDestSection

A null-terminated string specifies the destination section name in the INI file.

bFailIfExist

If the destination section already exists, it is replaced by the source section if this parameter is zero, otherwise the function fails.

Remarks

Copies an entire section including all its keys to another section. If the destination section does not exist, it is created.

Back to | Table of Contents | Class Interface |

BOOL CIni::MoveSection(LPCTSTR lpSrcSection, LPCTSTR lpDestSection, BOOL bFailIfExist = TRUE) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSrcSection

A null-terminated string specifies the source section name in the INI file.

lpDestSection

A null-terminated string specifies the destination section name in the INI file.

bFailIfExist

If the destination section already exists, it is replaced by the source section if this parameter is zero, otherwise the function fails.

Remarks

Moves an entire section including all its keys to another section. If the destination section does not exist, it is created.

Back to | Table of Contents | Class Interface |

BOOL CIni::DeleteSection(LPCTSTR lpSection) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

Remarks

Deletes an entire section including all its keys from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::IsKeyExist(LPCTSTR lpSection, LPCTSTR lpKey) const

Return Value

Returns non-zero if the key specified by lpKey exists in the section specified by lpSection in the INI file, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

Remarks

Checks for whether the specified key exists in the specified section in the INI file.

Back to | Table of Contents | Class Interface |

DWORD CIni::GetKeyLines(LPCTSTR lpSection, LPTSTR lpBuffer, DWORD dwBufSize) const

void CIni::GetKeyLines(LPCTSTR lpSection, CStringArray *pArray) const

Return Value

Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpBuffer

Points to the buffer that is to receive the copied key line list. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the key line list. String copied into lpBuffer is in "double-null terminated" format which can be parsed using CIni::ParseDNTString.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

pArray

Pointer to an MFC CStringArray object to receive the key line list.

Remarks

Retrieves a list of key lines in a specified section from the INI file. A key line is a string that consists of the key name, key value (optional), and the "=" sign (optional).

Back to | Table of Contents | Class Interface |

DWORD CIni::GetKeyNames(LPCTSTR lpSection, LPTSTR lpBuffer, DWORD dwBufSize) const

void CIni::GetKeyNames(LPCTSTR lpSection, CStringArray *pArray) const

Return Value

Specifies the length, in TCHAR, of the copied string, not including the terminating null character.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpBuffer

Points to the buffer that is to receive the copied key name list. If this parameter is NULL, the return value will be the actual length, in TCHAR, of the key name list. String copied into lpBuffer is in "double-null terminated" format which can be parsed using CIni::ParseDNTString.

dwBufSize

Specifies the maximum number of characters to be copied to the buffer. If the string is longer than the number of characters specified in dwBufSize, it is truncated.

pArray

Pointer to an MFC CStringArray object to receive the key name list.

Remarks

Retrieves a list of key names in a specified section from the INI file.

Back to | Table of Contents | Class Interface |

BOOL CIni::CopyKey(LPCTSTR lpSrcSection, LPCTSTR lpSrcKey, LPCTSTR lpDestSection, LPCTSTR lpDestKey, BOOL bFailIfExist) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSrcSection

A null-terminated string specifies the source section name in the INI file.

lpSrcKey

A null-terminated string specifies the source key name in the section specified by lpSrcSection in the INI file.

lpDestSection

A null-terminated string specifies the destination section name in the INI file.

lpDestKey

A null-terminated string specifies the destination key name in the section specified by lpDestSection in the INI file.

bFailIfExist

If the destination key already exists in the destination section, it is replaced by the source key if this parameter is zero, otherwise the function fails.

Remarks

Copies a specified key to another key. The copy may be cross-section. If the destination section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::MoveKey(LPCTSTR lpSrcSection, LPCTSTR lpSrcKey, LPCTSTR lpDestSection, LPCTSTR lpDestKey, BOOL bFailIfExist = TRUE) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSrcSection

A null-terminated string specifies the source section name in the INI file.

lpSrcKey

A null-terminated string specifies the source key name in the section specified by lpSrcSection in the INI file.

lpDestSection

A null-terminated string specifies the destination section name in the INI file.

lpDestKey

A null-terminated string specifies the destination key name in the section specified by lpDestSection in the INI file.

bFailIfExist

If the destination key already exists in the destination section, it is replaced by the source key if this parameter is zero, otherwise the function fails.

Remarks

Moves a specified key to another key. The move may be cross-section. If the destination section or key does not exist, they are created.

Back to | Table of Contents | Class Interface |

BOOL CIni::DeleteKey(LPCTSTR lpSection, LPCTSTR lpKey) const

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpSection

A null-terminated string specifies the section name in the INI file.

lpKey

A null-terminated string specifies the key name in the section specified by lpSection in the INI file.

Remarks

Deletes the specified key from the specified section.

Back to | Table of Contents | Class Interface |

typedef BOOL (CALLBACK *SUBSTRPROC)(LPCTSTR, LPVOID);

Remarks

Type definition of a user-defined CALLBACK function which will process sub-strings parsed from a "double-null terminated" string.

When called, the 1st parameter passed in will store the newly extracted sub-string, the 2nd parameter is a 32-bit user defined data, this parameter can be NULL. The parsing will terminate if this function returns zero. To use the callback, function pointer needs to be passed to CIni::ParseDNTString.

Back to | Table of Contents | Class Interface |

static BOOL CIni::ParseDNTString(LPCTSTR lpString, SUBSTRPROC lpFnStrProc, LPVOID lpParam = NULL)

Return Value

The function returns non-zero if succeeds, zero otherwise.

Parameters

lpString

A null-terminated string specifies the "double-null terminated" string to be parsed.

lpFnStrProc

Pointer to a SUBSTRPROC CALLBACK function which will process sub-strings parsed from lpString.

lpParam

A user-defined data which will be passed to lpFnStrProc. This parameter can be NULL.

Remarks

Parses a "double-null terminated" string. Every time after a sub-string is successfully extracted from the "double-null terminated" specified by lpString, the CALLBACK function pointed by lpFnStrProc is called and the sub-string is passed in. If the CALLBACK function returns non-zero, the parsing is continued until all sub-strings are extracted from lpString, or another call of the CALLBACK function returns zero.

Back to | Table of Contents | Class Interface |

History

Nov. 08, 2003

Initial public release.

Nov. 09, 2003

Fixed "GetString" and "GetPathName" method, changed parameter from "LPSTR" to "LPTSTR".
Added detailed description to "SUBSTRPROC" and "ParseDNTString".
Updated src and demo download files.

Nov. 10, 2003

Renamed method "GetKeys" to "GetKeyLines".
Added method "GetKeyNames".
Added parameter "bTrimString" to method "GetArray".
Improved the demo project so that users are less likely misspelling section/key names. Thanks to WREY for the suggestion, and thanks to Chris Maunder for his killer control. ;)
Updated src and demo download files.

Nov. 14, 2003

Used __AFXWIN_H__ instead of _AFXDLL to determine MFC presence.
Removed string length limit on INI file path name.
Removed "GetStruct" and "WriteStruct".
Added "GetDataBlock", "WriteDataBlock", and "AppendDataBlock".
Added "GetChar" and "WriteChar".
Updated src and demo download files.

Back to | Table of Contents |

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

About the Author

=[ Abin ]=

Member

Location:

China

Other popular C / C++ Language articles:

Member Function Pointers and the Fastest Possible C++ Delegates
A comprehensive tutorial on member function pointers, and an implementation of delegates that generates only two ASM opcodes!
How a C++ compiler implements exception handling
An indepth discussion of how VC++ implements exception handling. Source code includes exception handling library for VC++.
A Beginner's Guide to Pointers
An article showing the use of pointers in C and C++
XML class for processing and building simple XML documents
Link CMarkup into your VC++ app and avoid complex XML tools and dependencies
PugXML - A Small, Pugnacious XML Parser
Discussion of techniques for fast, robust, light-weight XML parsing.

Article Top

You must Sign In to use this message board.

FAQ
Noise Tolerance Layout Per page

Msgs 1 to 25 of 63 (Total in Forum: 63) (Refresh)

FirstPrevNext

Nice class, but would like WriteQuotedString() Fn

WilburrUK

11:07 16 Apr '09

Hi,

Thanks for this class, which I've quickly added to an application to remove the need to write registry keys.

Only had 2 problems making the changeover
1) saving strings with newlines in them obviously made a mess of the INI file (i ended up using WriteDataBlock() )

2) Saving strings with a trailing space (or more accurately re-reading them). I had to add \" marks to the strings on saving, then they loaded back in fine. A WriteQuotedString function would be nice, or just a check in WriteString( ) for iswhite on the last character.

Thanks again,
Wilburr.

VS 2008 - Errors without Unicode

Member 954266

21:59 22 Oct '08

I'm using this class in project in VS2008. With Unicode enabled, everything is ok. If I disable Unicode, I got about 6 error messages like:
error C3861: 'strtoul': identifier not found
error C3861: 'strtod': identifier not found

I found in MSDN, this two functions are defined in stdlib.h. So, if I added this header file to ini.h, it's ok. Where is problem? Is it error in ini.h or somewhere in my project settings?

Btw. this class is great

License

wukurtis

18:52 3 Jun '08

Hi there, great class and thank you for writing it. Is it possible to use this class in a commercial application? thanks.
Sign In·View Thread·PermaLink

VS 2008 - 2 errors, 13 warnings

Michael A. Rusakov

16:37 6 May '08

Hello,

Thank you for the useful class. However there are two errors when you try to compile the code with Visual Studio 2008. (And 13 warnings if UNICODE is enabled).

1. Ini.cpp(903) : error C2065: 'i' : undeclared identifier

The definition of 'i' should be moved outside operator 'for' in line 901.

2. Ini.cpp(623) : error C4430: missing type specifier - int assumed. Note: C++ does not support default-int

The line 623 should be changed from:
const LEN = GetKeyNames(lpSection, NULL, 0);
to
const DWORD LEN = GetKeyNames(lpSection, NULL, 0);

All warnings are about string functions. For example:
Ini.cpp(106) : warning C4996: 'wcsncpy': This function or variable may be unsafe. Consider using wcsncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

Thank you!

Sincerely,
Michael Rusakov.
http://www.wincatalog.com

Re: VS 2008 - 2 errors, 13 warnings

Laan82

3:36 24 Nov '08

Thank you michael without your advise I'll never be able to compile this class!
Sign In·View Thread·PermaLink

Compile time error occuring

Kaarthik Appuraj

1:17 13 Mar '08

Hi,
I am new to the INI file reading and windows programming,i downloaded the source file and added to my project.When i compiled the following three errors occured,could you please suggest me with some solution?It is very urgent for me
Error C2065:'strtoul':Undeclared identifier
Error C2065:'strtod':undeclared identifier
Error C2065:'strtol':undeclared identifier
The demo app is executing well,but the abover mentioned problem is occuring,pls very important can you suggest me what i should look for?

Cheers,
Karthik

Thanks & Regards,
Karthikeyan

Re: Compile time error occuring

Kaarthik Appuraj

2:08 13 Mar '08

Thanks guys the issue resolved,there was a problem with the downloaded source file
Cheers,
Kaarthik

Kaarthik Appuraj wrote:
Hi,
I am new to the INI file reading and windows programming,i downloaded the source file and added to my project.When i compiled the following three errors occured,could you please suggest me with some solution?It is very urgent for me
Error C2065:'strtoul':Undeclared identifier
Error C2065:'strtod':undeclared identifier
Error C2065:'strtol':undeclared identifier
The demo app is executing well,but the abover mentioned problem is occuring,pls very important can you suggest me what i should look for?

Cheers,
Karthik

Thanks & Regards,
Karthikeyan

Checkout SnapConfig

Member 3027110

9:28 3 Jan '08

at http://www.snapconfig.com if you are working with ini files its guaranteed to make your life easier. None
Sign In·View Thread·PermaLink	1.00/5 (1 vote)

Re: Checkout SnapConfig : A GUI tool NOT for FREE

ochoteau

23:43 11 Feb '08

It is only a GUI tool, to see/modify ini file which is not free So there is no integration with your C++ code
Sign In·View Thread·PermaLink

Re: Checkout SnapConfig :

SnapConfig

7:27 13 Feb '08

True but if you are working with ini files you'll quickly realize the value of this tool. I've worked on several projects which had ini files and without such a tool it very quickly eats up developer hours during development and testing. though i should've done Check out SnapConfig None
Sign In·View Thread·PermaLink

Buffer is too small msg

Dimz

21:25 13 Nov '07

Hello. In __KeyPairProc(...) in copy to the buffer section should be `_tcsncpy_s(psl->lpTarget, dwCopyLen+1, psz, dwCopyLen);` instead of `_tcsncpy_s(psl->lpTarget, dwCopyLen, psz, dwCopyLen);`
Sign In·View Thread·PermaLink

very useful

Tron3000

8:30 15 Aug '07

Very useful class for my applications... Thanks a lot!
Sign In·View Thread·PermaLink

quick enhancment: put INI in same dir as EXE

SGarratt

14:13 30 Jul '07

wont work with constructor method.

CIni ini;
ini.SetIniNameInExeDir("config.ini"); //should ck return TRUE

add include shown and add to cini.cpp amd proto to .h.

#include ;

BOOL CIni::SetIniNameInExeDir(LPCTSTR lpIniName)
{
TCHAR modname[MAX_PATH];
DWORD dw = GetModuleFileName(NULL,modname,MAX_PATH);
if(dw == 0) return FALSE;
PathRemoveFileSpec(modname);
if((_tcslen(lpIniName) + 1 + dw) > MAX_PATH) return FALSE;
_tcsncat(modname,_T("\\"),MAX_PATH);
_tcsncat(modname,lpIniName,MAX_PATH);
SetPathName(modname);
return TRUE;
}

SGarratt

error unsupported operation

xRomano

6:49 8 Apr '07

Hi When i try to use the ini.h and ini.cpp files in my mfc project i get this error: An unsupported operation was attempted, after this my app starts fine but no config file is created. Any help?
Sign In·View Thread·PermaLink

CIni to handle inline comment

Yoong Hor Meng

5:55 21 Mar '07

Hi: I have implemented handling of inline comment, for example: [System] FilePath=C:\WinNT\System32\aa.dll ; This is a demo FileSize=356 ; This is the file size I do not know where I should post it as I do not own the right of the original code. Please advise. Regards Yoong
Sign In·View Thread·PermaLink

Fixes for memory allocation/deallocation

Yoong Hor Meng

15:46 17 Mar '07

Hi:

Please refer to

http://www.codeproject.com/cpp/CIni.asp?df=100&forumid=25966&select=965813#xx965813xx[^]
free() shall be used instead of delete for _strdup() function. I also suggest to change all the delete to free(). For example,

From

DWORD CIni::GetString(LPCTSTR lpSection, LPCTSTR lpKey, LPTSTR lpBuffer, DWORD dwBufSize, LPCTSTR lpDefault) const
{
	if (lpBuffer != NULL)
		*lpBuffer = _T('\0');

	LPTSTR psz = __GetStringDynamic(lpSection, lpKey, lpDefault);
	DWORD dwLen = _tcslen(psz);

	if (lpBuffer != NULL)
	{
		_tcsncpy(lpBuffer, psz, dwBufSize);
		dwLen = min(dwLen, dwBufSize);
	}

	delete [] psz;
	return dwLen;
}

DWORD CIni::GetString(LPCTSTR lpSection, LPCTSTR lpKey, LPTSTR lpBuffer, DWORD dwBufSize, LPCTSTR lpDefault) const
{
	if (lpBuffer != NULL)
		*lpBuffer = _T('\0');

	LPTSTR psz = __GetStringDynamic(lpSection, lpKey, lpDefault);
	DWORD dwLen = _tcslen(psz);

	if (lpBuffer != NULL)
	{
		_tcsncpy(lpBuffer, psz, dwBufSize);
		dwLen = min(dwLen, dwBufSize);
	}

	free(psz);
	return dwLen;
}

Regards
Yoong

nice class

chrische5

12:33 17 Nov '06

Thanks for your work. A very usefull class and a good looking demo. The only point for updating are the warnings. www.russische-hortkinder.de
Sign In·View Thread·PermaLink	2.00/5 (1 vote)

non MFC demo

djorge111

2:51 14 Feb '06

Hello. This class is very impressive!! I am trying to use your class in a non MFC utility, but i am getting some difficulties in getting all the names of a section. Could you provide a small example of how to do this?
Sign In·View Thread·PermaLink	2.00/5 (2 votes)

Support Unicode?

5:23 7 Aug '05

how it works with wchar* ?
Sign In·View Thread·PermaLink	1.25/5 (5 votes)

Awesome

FlyingBearcat

15:08 15 Jul '05

Sir, I just want to thank you for this class, I had some trouble with the earlier source of course, but once I downloaded the most recent version it worked fine. (.NET MFC Dialog Based App) It's really a great class, works well, intuitive, easy to import, and what I like most is all the little work you've put into it. Very nice work and thankyou very much. Let's Fly
Sign In·View Thread·PermaLink

Anyone get it to work in .NET environment.

fhebert

6:29 28 Mar '05

I am new to .net and trying to learn it by converting some existing code. I have a simple program that stores its defaults from run to run in an INI file. Your CIni looked pretty neat so rather than re-invent the wheel, I tried to use it but...

From your example:
m_sDelimiter = ini.GetString(_T("Settings"), _T("Delimiter"), _T(","));

My code:
IpEdit->Text = ini.GetString(_T("DEFAULTS"),_T("IpAddress"),_T("10.1.1.1"));

Compiler complains that "CIni::GetString function does not take 3 arguments". Obviously a bogus error, but why?

1.00/5 (2 votes)

dirty code

califf_usa

10:35 18 Feb '05

This code generates lots of warnings even with WARNING LEVEL set to 3. This is not professional.
Sign In·View Thread·PermaLink	1.33/5 (2 votes)

Allocation conflict.

Anthony_Yio

22:18 4 Nov '04

Happen to know this when the memory checker prompted me .It seems that

in your dtor, you are using delete to free the memory.

CIni::~CIni()
{
if (m_pszPathName != NULL)
delete [] m_pszPathName;
}

and in your SetPathName(...)

if (m_pszPathName != NULL)
delete [] m_pszPathName;

According to MSDN, _strdup calls malloc to allocate storage space for the copy of strSource.
I think the proper memory release routine is free(m_pszPathName).

Other than this, it is a nicely written codes. Use it and like it.

Sonork 100.41263:Anthony_Yio

Re: Allocation conflict.

Mfc_King

2:06 15 Aug '05

The _strdup function() calls malloc() to allocate storage space for a copy of strSource and then copies strSource to the allocated space. Because _strdup() calls malloc to allocate storage space for the copy of strSource, it is good practice always to release this memory by calling the free() routine on the pointer returned by the call to _strdup.
Sign In·View Thread·PermaLink

Having trouble with GetKeyNames

nigma_x

22:40 26 Aug '04

I'm using Visual C++.net 2002. I'm using CIni in an MFC. The problem I'm having is I Can declare the CStringArray in the function. Pass it to GetKeyNames. I'm unable to access any of the elements in the Array. Don't know If I'm declaring the array correct or not. I've tried to declare the CStringArray variable using the variable wizard. This allows me to access the elements but I'm unable to pass the array to GetKeyNames. Sort of new with C++ MFC. Any help would be great. This is the code so far. What I'm tring to do is get a list of the Keys in a section and display them in a Edit Control.

void CRunProgramDlg::OnBnClickedOk()
{
	//// TODO: Add your control notification handler code here

	
	
    
	
	LPTSTR    Current = NULL;
	DWORD	  dwBuffer = 100;
	CString ArrayString;
	
	//CStringArray Declared with the variable wizard and using 
        //Using SetSize to set the size of the array
	m_FindKey.SetSize(32,0);
	
	//CStringArray declared in the function set array to 1
        CStringArray ProfileSearch[1];

	CIni ini;
	ini.SetPathName("C:\\amrtemp\\file2.ini");
	ini.GetKeyNames("Routing Indicator",Current,dwBuffer);
        
        //When using this CStringArray in GetKeyNames recieve error
        // error C2664: 'void CIni::GetKeyNames(LPCTSTR,CStringArray *) 
        // const' : cannot  convert parameter 2 from 'CStringArray' to 'CStringArray *
	ini.GetKeyNames("Routing Indicator",m_FindKey);

        //When using this CStringArray in ProfileSearch I don't recieve an error here
	ini.GetKeyNames("Routing Indicator",ProfileSearch);
	
	
	
	 

        //Don't know if this works.  Wont'compile after ini.GetKeyNames 
        //("RoutingIndicator",m_FindKey);
	ArrayString = m_FindKey.GetAt(1);
        
        //Recieve error C2679: binary '=' : no operator found which takes a right-hand
        //operand of type 'CStringArray' (or there is no acceptable conversion)
        ArrayString = ProfileSearch[1];
		
	m_strBrowse = ini.GetString("Routing Indicator", ArrayString,"Dev");
	
	
	
	UpdateData(FALSE);

I'm at a loss Confused

I don't think I'm declaring the variables correctly.

Last Visit: 16:01 23 Nov '09 Last Update: 16:01 23 Nov '09

12 3 Next »

General News Question Answer Joke Rant Admin

PermaLink | Privacy | Terms of Use
Last Updated: 13 Nov 2003
Editor: Smitha Vijayan

CIni

Table of Contents

Introduction

What INI Files Are

Why Another Class

What Do We Get

How to Use

Class Interface

Constructors

INI File Path Access

String Access

Integer Access

Boolean Access

Char Access

Double Access

Structure Access

Section Manipulation

Key Manipulation

Double-Null Terminated String Parsing

Method Description

Parameters

Remarks

Parameters

Remarks

Return Value

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Return Value

Parameters

Remarks

Return Value

Parameters

Return Value

Parameters

Remarks

Return Value

Parameters

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks

Return Value

Parameters

Remarks