Click here to Skip to main content
15,860,844 members
Articles / Programming Languages / C++
Article

CIni

Rate me:
Please Sign up or sign in to vote.
4.94/5 (57 votes)
13 Nov 200328 min read 253.5K   12.4K   182   69
A comprehensive INI file handling class.

Sample Image - CIni_Demo.gif

Table of Contents

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

Constructors

CIni

INI File Path Access

SetPathName, GetPathName

String Access

GetString, WriteString, AppendString, GetArray, WriteArray

Integer Access

GetInt, WriteInt, IncreaseInt, GetUInt, WriteUInt, IncreaseUInt

Boolean Access

GetBool, WriteBool, InvertBool

Char Access

GetChar, WriteChar

Double Access

GetDouble, WriteDouble, IncreaseDouble

Structure Access

GetPoint, WritePoint, GetRect, WriteRect, GetDataBlock, WriteDataBlock, AppendDataBlock

Section Manipulation

IsSectionExist, GetSectionNames, CopySection, MoveSection, DeleteSection

Key Manipulation

IsKeyExist, GetKeyLines, GetKeyNames, CopyKey, MoveKey, DeleteKey

Double-Null Terminated String Parsing

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

ParseDNTString

Back to | Table of Contents |

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

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

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


Written By
China China
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

 
GeneralAwesome Pin
FlyingBearcat15-Jul-05 14:08
FlyingBearcat15-Jul-05 14:08 
GeneralAnyone get it to work in .NET environment. Pin
Member 183499128-Mar-05 5:29
Member 183499128-Mar-05 5:29 
Generaldirty code Pin
CALIFF218-Feb-05 9:35
CALIFF218-Feb-05 9:35 
GeneralAllocation conflict. Pin
Anthony_Yio4-Nov-04 21:18
Anthony_Yio4-Nov-04 21:18 
GeneralRe: Allocation conflict. Pin
Mfc_King15-Aug-05 1:06
Mfc_King15-Aug-05 1:06 
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.
GeneralHaving trouble with GetKeyNames Pin
nigma_x26-Aug-04 21:40
nigma_x26-Aug-04 21:40 
GeneralINI file without any section Pin
pankajks12-Aug-04 19:20
pankajks12-Aug-04 19:20 
GeneralJust perfect for me Pin
x-b30-Jun-04 2:51
x-b30-Jun-04 2:51 
GeneralHandling of comments in ini file Pin
Igor Rikalo28-Mar-04 6:17
Igor Rikalo28-Mar-04 6:17 
GeneralAbout __TrimString Function Pin
yao_xuejun19-Feb-04 17:15
yao_xuejun19-Feb-04 17:15 
GeneralRe: About __TrimString Function Pin
Abin20-Feb-04 1:22
Abin20-Feb-04 1:22 
GeneralAbout Win98 Pin
Anthony_Yio15-Dec-03 21:49
Anthony_Yio15-Dec-03 21:49 
GeneralRe: About Win98 Pin
#realJSOP31-Dec-03 8:53
mve#realJSOP31-Dec-03 8:53 
GeneralRe: About Win98 Pin
Anthony_Yio1-Jan-04 14:26
Anthony_Yio1-Jan-04 14:26 
GeneralMake an ActiveX control of it Pin
Ammar17-Nov-03 20:37
Ammar17-Nov-03 20:37 
GeneralRe: Make an ActiveX control of it Pin
Anthony_Yio1-Jan-04 14:28
Anthony_Yio1-Jan-04 14:28 
GeneralDetection of MFC-based compilation Pin
SchweinDeBurg15-Nov-03 5:02
SchweinDeBurg15-Nov-03 5:02 
GeneralRe: Detection of MFC-based compilation Pin
Abin15-Nov-03 5:19
Abin15-Nov-03 5:19 
GeneralLooks pretty good - suggestions Pin
Rick York14-Nov-03 6:24
mveRick York14-Nov-03 6:24 
GeneralWont compile Pin
Daniel132413-Nov-03 16:19
Daniel132413-Nov-03 16:19 
GeneralRe: Wont compile Pin
Abin14-Nov-03 4:46
Abin14-Nov-03 4:46 
GeneralMissing Data types Pin
sinverso12-Nov-03 13:04
sinverso12-Nov-03 13:04 
GeneralRe: Missing Data types Pin
Anonymous13-Nov-03 1:39
Anonymous13-Nov-03 1:39 
GeneralSuggestion to simplify the interface Pin
inspeckpr11-Nov-03 9:11
inspeckpr11-Nov-03 9:11 
GeneralRe: Suggestion to simplify the interface Pin
Anonymous12-Nov-03 5:17
Anonymous12-Nov-03 5:17 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.