nsIINIParserWriter

This article needs a technical review. How you can help.

nsIINIParserWriter

Allows writing to an INI-format configuration file.
1.0
35
Introduced
Gecko 1.9.2
Inherits from: nsISupports Last changed in Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)

This interface provides methods that allow writing to INI-format configuration files. INI files contain zero or more sections, denoted by a name in square brackets, followed by zero or more lines of text with a property name on the left, then an equals sign ("="), then the value of the property.

To create an nsIINIParserWriter object, you use the nsIINIParserFactory interface to create a parser, then nsISupports.QueryInterface() that to get an nsIINIParserWriter, like this:

let writer = Components.classes["@mozilla.org/xpcom/ini-processor-factory;1"].
                       .getService(Components.interfaces.nsIINIParserFactory)
                       .createINIParser(someLocalFile)
                       .QueryInterface(Components.interfaces.nsIINIParserWriter);

Here, someLocalFile is an nsIFile based object, such as an nsILocalFile. This indicates the file into which the INI data will be written.

Once the writer object is created, you can use the setString() method to set the value of a property within a given section; the section is created if it hasn't been yet.

The sections are built in memory before the text of the INI file is generated, so you can add properties to the file in any order, regardless of section.

When you're done and ready to write the INI file to disk, call the writeFile() method.

Method overview

void setString(in AUTF8String aSection, in AUTF8String aKey, in AUTF8String aValue);
void writeFile([optional] in nsIFile aINIFile, [optional] in unsigned long aFlags);

Constants

File writing constants

These constants are specified when calling writeFile(), in order to change its behavior.

Constant Value Description
WRITE_UTF16 0x1 Windows and the NSIS installer code sometimes expect INI files to be in UTF-16 encoding. On Windows only, this flag to writeFile() can be used to change the encoding from its default UTF-8.

Methods

setString()

Set the value of a property string for a particular section and key.

void setString(
  in AUTF8String aSection,
  in AUTF8String aKey,
  in AUTF8String aValue
);
Parameters
aSection
The name of the section into which to place the property.
aKey
The name of the property for which the value is to be set.
aValue
The value to assign to the property.

writeFile()

Write to the INI file.

void writeFile(
  in nsIFile aINIFile, Optional
  in unsigned long aFlags Optional 
);
Parameters
aINIFile Optional
If specified, this nsIFile based object is used as the output file instead of the one specified at initialization time (if any).
aFlags Optional
Flags controlling the file write operation. See File writing constants for details on the permitted values.

See also

Document Tags and Contributors

 Contributors to this page: kscarfone, Sheppy
 Last updated by: kscarfone,