xpcom/base/nsID.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 #ifndef nsID_h__
   8 #define nsID_h__
   9
  10 #include <string.h>
  11
  12 #include "nscore.h"
  13
  14 #define NSID_LENGTH 39
  15
  16 #ifndef XPCOM_GLUE_AVOID_NSPR
  17 class nsIDToCString;
  18 #endif
  19
  20 /**
  21  * A "unique identifier". This is modeled after OSF DCE UUIDs.
  22  */
  23
  24 struct nsID {
  25   uint32_t m0;
  26   uint16_t m1;
  27   uint16_t m2;
  28   uint8_t m3[8];
  29
  30   /**
  31    * Create a new random UUID.
  32    * GenerateUUIDInPlace() is fallible, whereas GenerateUUID() will abort in
  33    * the unlikely case that the OS RNG returns an error.
  34    */
  35   [[nodiscard]] static nsresult GenerateUUIDInPlace(nsID& aId);
  36   static nsID GenerateUUID();
  37
  38   /**
  39    * Ensures everything is zeroed out.
  40    */
  41   void Clear();
  42
  43   /**
  44    * Equivalency method. Compares this nsID with another.
  45    * @return true if they are the same, false if not.
  46    */
  47
  48   inline bool Equals(const nsID& aOther) const {
  49     // At the time of this writing, modern compilers (namely Clang) inline this
  50     // memcmp call into a single SIMD operation on x86/x86-64 architectures (as
  51     // long as we compare to zero rather than returning the full integer return
  52     // value), which is measurably more efficient to any manual comparisons we
  53     // can do directly.
  54 #if defined(__x86_64__) || defined(__i386__)
  55     return !memcmp(this, &aOther, sizeof *this);
  56 #else
  57     // However, on ARM architectures, compilers still tend to generate a direct
  58     // memcmp call, which we'd like to avoid.
  59     return (((uint32_t*)&m0)[0] == ((uint32_t*)&aOther.m0)[0]) &&
  60            (((uint32_t*)&m0)[1] == ((uint32_t*)&aOther.m0)[1]) &&
  61            (((uint32_t*)&m0)[2] == ((uint32_t*)&aOther.m0)[2]) &&
  62            (((uint32_t*)&m0)[3] == ((uint32_t*)&aOther.m0)[3]);
  63 #endif
  64   }
  65
  66   inline bool operator==(const nsID& aOther) const { return Equals(aOther); }
  67
  68   /**
  69    * nsID Parsing method. Turns a {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
  70    * string into an nsID
  71    */
  72   bool Parse(const char* aIDStr);
  73
  74 #ifndef XPCOM_GLUE_AVOID_NSPR
  75   /**
  76    * nsID string encoder. Returns a managed string in
  77    * {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format.
  78    */
  79   nsIDToCString ToString() const;
  80
  81   /**
  82    * nsID string encoder. Builds a string in
  83    * {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format, into a char[NSID_LENGTH]
  84    * buffer provided by the caller (for instance, on the stack).
  85    */
  86   void ToProvidedString(char (&aDest)[NSID_LENGTH]) const;
  87
  88 #endif  // XPCOM_GLUE_AVOID_NSPR
  89
  90   // Infallibly duplicate an nsID. Must be freed with free().
  91   nsID* Clone() const;
  92 };
  93
  94 #ifndef XPCOM_GLUE_AVOID_NSPR
  95 /**
  96  * A stack helper class to convert a nsID to a string.  Useful
  97  * for printing nsIDs.  For example:
  98  *   nsID aID = ...;
  99  *   printf("%s", nsIDToCString(aID).get());
 100  */
 101 class nsIDToCString {
 102  public:
 103   explicit nsIDToCString(const nsID& aID) {
 104     aID.ToProvidedString(mStringBytes);
 105   }
 106
 107   const char* get() const { return mStringBytes; }
 108
 109  protected:
 110   char mStringBytes[NSID_LENGTH];
 111 };
 112 #endif
 113
 114 /*
 115  * Class IDs
 116  */
 117
 118 typedef nsID nsCID;
 119
 120 // Define an CID
 121 #define NS_DEFINE_CID(_name, _cidspec) const nsCID _name = _cidspec
 122
 123 #define NS_DEFINE_NAMED_CID(_name) static const nsCID k##_name = _name
 124
 125 #define REFNSCID const nsCID&
 126
 127 /**
 128  * An "interface id" which can be used to uniquely identify a given
 129  * interface.
 130  */
 131
 132 typedef nsID nsIID;
 133
 134 /**
 135  * A macro shorthand for <tt>const nsIID&<tt>
 136  */
 137
 138 #define REFNSIID const nsIID&
 139
 140 /**
 141  * A macro to build the static const IID accessor method. The Dummy
 142  * template parameter only exists so that the kIID symbol will be linked
 143  * properly (weak symbol on linux, gnu_linkonce on mac, multiple-definitions
 144  * merged on windows). Dummy should always be instantiated as "void".
 145  */
 146
 147 #define NS_DECLARE_STATIC_IID_ACCESSOR(the_iid) \
 148   template <typename T, typename U>             \
 149   struct COMTypeInfo;
 150
 151 #define NS_DEFINE_STATIC_IID_ACCESSOR(the_interface, the_iid)                \
 152   template <typename T>                                                      \
 153   struct the_interface::COMTypeInfo<the_interface, T> {                      \
 154     static const nsIID kIID NS_HIDDEN;                                       \
 155   };                                                                         \
 156   template <typename T>                                                      \
 157   const nsIID the_interface::COMTypeInfo<the_interface, T>::kIID NS_HIDDEN = \
 158       the_iid;
 159
 160 /**
 161  * A macro to build the static const CID accessor method
 162  */
 163
 164 #define NS_DEFINE_STATIC_CID_ACCESSOR(the_cid) \
 165   static const nsID& GetCID() {                \
 166     static const nsID cid = the_cid;           \
 167     return cid;                                \
 168   }
 169
 170 #define NS_GET_IID(T) (T::COMTypeInfo<T, void>::kIID)
 171 #define NS_GET_TEMPLATE_IID(T) (T::template COMTypeInfo<T, void>::kIID)
 172
 173 #endif