xpcom/components/nsICategoryManager.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsISupportsPrimitives.idl"
   8
   9 interface nsISimpleEnumerator;
  10
  11 %{C++
  12 #include "nsString.h"
  13 %}
  14
  15 /*
  16  * nsICategoryManager
  17  */
  18
  19 [scriptable, builtinclass, uuid(de021d54-57a3-4025-ae63-4c8eedbe74c0)]
  20 interface nsICategoryEntry : nsISupportsCString
  21 {
  22   readonly attribute ACString entry;
  23
  24   readonly attribute ACString value;
  25 };
  26
  27 [builtinclass, scriptable, uuid(3275b2cd-af6d-429a-80d7-f0c5120342ac)]
  28 interface nsICategoryManager : nsISupports
  29 {
  30     /**
  31      * Get the value for the given category's entry.
  32      * @param aCategory The name of the category ("protocol")
  33      * @param aEntry The entry you're looking for ("http")
  34      * @return The value.
  35      */
  36     ACString getCategoryEntry(in ACString aCategory, in ACString aEntry);
  37
  38     /**
  39      * Add an entry to a category.
  40      * @param aCategory The name of the category ("protocol")
  41      * @param aEntry The entry to be added ("http")
  42      * @param aValue The value for the entry ("moz.httprulez.1")
  43      * @param aPersist Should this data persist between invocations?
  44      * @param aReplace Should we replace an existing entry?
  45      * @return Previous entry, if any
  46      */
  47     ACString addCategoryEntry(in ACString aCategory, in ACString aEntry,
  48                               in ACString aValue, in boolean aPersist,
  49                               in boolean aReplace);
  50
  51     /**
  52      * Delete an entry from the category.
  53      * @param aCategory The name of the category ("protocol")
  54      * @param aEntry The entry to be added ("http")
  55      * @param aPersist Delete persistent data from registry, if present?
  56      */
  57     void deleteCategoryEntry(in ACString aCategory, in ACString aEntry,
  58                              in boolean aPersist);
  59
  60     /**
  61      * Delete a category and all entries.
  62      * @param aCategory The category to be deleted.
  63      */
  64     void deleteCategory(in ACString aCategory);
  65
  66     /**
  67      * Enumerate the entries in a category.
  68      * @param aCategory The category to be enumerated.
  69      * @return a simple enumerator, each result QIs to
  70      *         nsICategoryEntry.
  71      */
  72     nsISimpleEnumerator enumerateCategory(in ACString aCategory);
  73
  74
  75     /**
  76      * Enumerate all existing categories
  77      * @param aCategory The category to be enumerated.
  78      * @return a simple enumerator, each result QIs to
  79      *         nsISupportsCString.
  80      */
  81     nsISimpleEnumerator enumerateCategories();
  82
  83     %{C++
  84     template<size_t N>
  85     nsresult
  86     GetCategoryEntry(const char (&aCategory)[N], const nsACString& aEntry,
  87                      nsACString& aResult)
  88     {
  89         return GetCategoryEntry(nsLiteralCString(aCategory),
  90                                 aEntry, aResult);
  91     }
  92
  93     template<size_t N, size_t M>
  94     nsresult
  95     GetCategoryEntry(const char (&aCategory)[N], const char (&aEntry)[M],
  96                      nsACString& aResult)
  97     {
  98         return GetCategoryEntry(nsLiteralCString(aCategory),
  99                                 nsLiteralCString(aEntry),
 100                                 aResult);
 101     }
 102
 103     nsresult
 104     AddCategoryEntry(const nsACString& aCategory, const nsACString& aEntry,
 105                      const nsACString& aValue, bool aPersist, bool aReplace)
 106     {
 107         nsCString oldValue;
 108         return AddCategoryEntry(aCategory, aEntry, aValue, aPersist, aReplace,
 109                                 oldValue);
 110     }
 111
 112     template<size_t N>
 113     nsresult
 114     AddCategoryEntry(const char (&aCategory)[N], const nsACString& aEntry,
 115                      const nsACString& aValue, bool aPersist, bool aReplace)
 116     {
 117         nsCString oldValue;
 118         return AddCategoryEntry(nsLiteralCString(aCategory), aEntry, aValue,
 119                                 aPersist, aReplace, oldValue);
 120     }
 121
 122     template<size_t N>
 123     nsresult
 124     DeleteCategoryEntry(const char (&aCategory)[N], const nsACString& aEntry, bool aPersist)
 125     {
 126         return DeleteCategoryEntry(nsLiteralCString(aCategory), aEntry, aPersist);
 127     }
 128
 129
 130     template<size_t N>
 131     nsresult
 132     EnumerateCategory(const char (&aCategory)[N], nsISimpleEnumerator** aResult)
 133     {
 134         return EnumerateCategory(nsLiteralCString(aCategory), aResult);
 135     }
 136     %}
 137 };