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