xpcom/base/nsINIParser.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 // This file was shamelessly copied from mozilla/xpinstall/wizard/unix/src2
   8
   9 #ifndef nsINIParser_h__
  10 #define nsINIParser_h__
  11
  12 #ifdef MOZILLA_INTERNAL_API
  13 #  define nsINIParser nsINIParser_internal
  14 #endif
  15
  16 #include "nscore.h"
  17 #include "nsClassHashtable.h"
  18 #include "mozilla/UniquePtr.h"
  19
  20 #include <stdio.h>
  21
  22 class nsIFile;
  23
  24 class nsINIParser {
  25  public:
  26   nsINIParser() {}
  27   ~nsINIParser() = default;
  28
  29   /**
  30    * Initialize the INIParser with a nsIFile. If this method fails, no
  31    * other methods should be called. This method reads and parses the file,
  32    * the class does not hold a file handle open. An instance must only be
  33    * initialized once.
  34    */
  35   nsresult Init(nsIFile* aFile);
  36
  37   nsresult InitFromString(const nsCString& aStr);
  38
  39   /**
  40    * Callback for GetSections
  41    * @return false to stop enumeration, or true to continue.
  42    */
  43   typedef bool (*INISectionCallback)(const char* aSection, void* aClosure);
  44
  45   /**
  46    * Enumerate the sections within the INI file.
  47    */
  48   nsresult GetSections(INISectionCallback aCB, void* aClosure);
  49
  50   /**
  51    * Callback for GetStrings
  52    * @return false to stop enumeration, or true to continue
  53    */
  54   typedef bool (*INIStringCallback)(const char* aString, const char* aValue,
  55                                     void* aClosure);
  56
  57   /**
  58    * Enumerate the strings within a section. If the section does
  59    * not exist, this function will silently return.
  60    */
  61   nsresult GetStrings(const char* aSection, INIStringCallback aCB,
  62                       void* aClosure);
  63
  64   /**
  65    * Get the value of the specified key in the specified section
  66    * of the INI file represented by this instance.
  67    *
  68    * @param aSection      section name
  69    * @param aKey          key name
  70    * @param aResult       the value found
  71    * @throws NS_ERROR_FAILURE if the specified section/key could not be
  72    *                          found.
  73    */
  74   nsresult GetString(const char* aSection, const char* aKey,
  75                      nsACString& aResult);
  76
  77   /**
  78    * Alternate signature of GetString that uses a pre-allocated buffer
  79    * instead of a nsACString (for use in the standalone glue before
  80    * the glue is initialized).
  81    *
  82    * @throws NS_ERROR_LOSS_OF_SIGNIFICANT_DATA if the aResult buffer is not
  83    *         large enough for the data. aResult will be filled with as
  84    *         much data as possible.
  85    *
  86    * @see GetString [1]
  87    */
  88   nsresult GetString(const char* aSection, const char* aKey, char* aResult,
  89                      uint32_t aResultLen);
  90
  91   /**
  92    * Sets the value of the specified key in the specified section. The section
  93    * is created if it does not already exist.
  94    *
  95    * @oaram aSection      section name
  96    * @param aKey          key name
  97    * @param aValue        the value to set
  98    */
  99   nsresult SetString(const char* aSection, const char* aKey,
 100                      const char* aValue);
 101
 102   /**
 103    * Deletes the value of the specified key in the specified section.
 104    *
 105    * @param aSection      section name
 106    * @param aKey          key name
 107    *
 108    * @throws NS_ERROR_FAILURE if the string was not set.
 109    */
 110   nsresult DeleteString(const char* aSection, const char* aKey);
 111
 112   /**
 113    * Deletes the specified section.
 114    *
 115    * @param aSection      section name
 116    *
 117    * @throws NS_ERROR_FAILURE if the section did not exist.
 118    */
 119   nsresult DeleteSection(const char* aSection);
 120
 121   /**
 122    * Renames the specified section.
 123    *
 124    * @param aSection      section name
 125    * @param aNewName      new section name
 126    *
 127    * @throws NS_ERROR_FAILURE if the section did not exist.
 128    * @throws NS_ERROR_ILLEGAL_VALUE if the new section name already exists.
 129    */
 130   nsresult RenameSection(const char* aSection, const char* aNewName);
 131
 132   /**
 133    * Writes the ini data to disk.
 134    * @param aFile         the file to write to
 135    * @throws NS_ERROR_FAILURE on failure.
 136    */
 137   nsresult WriteToFile(nsIFile* aFile);
 138
 139   void WriteToString(nsACString& aOutput);
 140
 141  private:
 142   struct INIValue {
 143     INIValue(const char* aKey, const char* aValue)
 144         : key(strdup(aKey)), value(strdup(aValue)) {}
 145
 146     ~INIValue() {
 147       delete key;
 148       delete value;
 149     }
 150
 151     void SetValue(const char* aValue) {
 152       delete value;
 153       value = strdup(aValue);
 154     }
 155
 156     const char* key;
 157     const char* value;
 158     mozilla::UniquePtr<INIValue> next;
 159   };
 160
 161   nsClassHashtable<nsCharPtrHashKey, INIValue> mSections;
 162
 163   bool IsValidSection(const char* aSection);
 164   bool IsValidKey(const char* aKey);
 165   bool IsValidValue(const char* aValue);
 166 };
 167
 168 #endif /* nsINIParser_h__ */