CIni 配置文件ini

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 | |

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 | |

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 | |

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 | |

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 | |

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

Back to | |

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 | ||

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 .

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 .

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 .

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 | | |

---

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 .

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 | | |

---

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 | | |

---

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 | | |

---

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 | | |

---

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 .

Back to | | |

---

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 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 | | |

---

History

Nov. 08, 2003

• Initial public release.

Nov. 09, 2003

• Fixed "" and "" method, changed parameter from "LPSTR" to "LPTSTR".
• Added detailed description to "" and "".
• Updated and download files.

Nov. 10, 2003

• Renamed method "GetKeys" to "".
• Added method "".
• Added parameter "bTrimString" to method "".
• 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 and 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 "", "", and "".
• Added "" and "".
• Updated and download files.

Back to | |

---

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