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
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
CIni ini(_T("c:\\test.ini"));
int data[3] = { 202, -126, 6500 };
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
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 |
