xpcom/build/nsXPCOM.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 nsXPCOM_h__
   8 #define nsXPCOM_h__
   9
  10 #include "nscore.h"
  11 #include "nsXPCOMCID.h"
  12 #include "mozilla/Attributes.h"
  13 #include "mozilla/Atomics.h"
  14
  15 #ifdef __cplusplus
  16 #  define DECL_CLASS(c) class c
  17 #  define DECL_STRUCT(c) struct c
  18 #else
  19 #  define DECL_CLASS(c) typedef struct c c
  20 #  define DECL_STRUCT(c) typedef struct c c
  21 #endif
  22
  23 DECL_CLASS(nsISupports);
  24 DECL_CLASS(nsIModule);
  25 DECL_CLASS(nsIComponentManager);
  26 DECL_CLASS(nsIComponentRegistrar);
  27 DECL_CLASS(nsIServiceManager);
  28 DECL_CLASS(nsIFile);
  29 DECL_CLASS(nsIDirectoryServiceProvider);
  30 DECL_CLASS(nsIMemory);
  31 DECL_CLASS(nsIDebug2);
  32
  33 #ifdef __cplusplus
  34 extern bool gXPCOMShuttingDown;
  35 extern mozilla::Atomic<bool, mozilla::SequentiallyConsistent>
  36     gXPCOMThreadsShutDown;
  37 extern bool gXPCOMMainThreadEventsAreDoomed;
  38 #endif
  39
  40 #ifdef __cplusplus
  41 #  include "nsStringFwd.h"
  42 #endif
  43
  44 /**
  45  * Initialises XPCOM. You must call one of the NS_InitXPCOM methods
  46  * before proceeding to use xpcom. The one exception is that you may
  47  * call NS_NewLocalFile to create a nsIFile.
  48  *
  49  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE>
  50  *       to create the file object you supply as the bin directory path in this
  51  *       call. The function may be safely called before the rest of XPCOM or
  52  *       embedding has been initialised.
  53  *
  54  * @param aResult          The service manager.  You may pass null.
  55  *
  56  * @param aBinDirectory    The directory containing the component
  57  *                         registry and runtime libraries;
  58  *                         or use <CODE>nullptr</CODE> to use the working
  59  *                         directory.
  60  *
  61  * @param aAppFileLocationProvider The object to be used by Gecko that
  62  *                         specifies to Gecko where to find profiles, the
  63  *                         component registry preferences and so on; or use
  64  *                         <CODE>nullptr</CODE> for the default behaviour.
  65  *
  66  * @param aInitJSContext   Whether the nsXPCJSContext should be initialized at
  67  *                         this point.
  68  *
  69  * @see NS_NewLocalFile
  70  * @see nsIFile
  71  * @see nsIDirectoryServiceProvider
  72  *
  73  * @return NS_OK for success;
  74  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
  75  *         which can happen if XPCOM is reloaded, but did not completly
  76  *         shutdown. Other error codes indicate a failure during
  77  *         initialisation.
  78  */
  79 XPCOM_API(nsresult)
  80 NS_InitXPCOM(nsIServiceManager** aResult, nsIFile* aBinDirectory,
  81              nsIDirectoryServiceProvider* aAppFileLocationProvider,
  82              bool aInitJSContext = true);
  83
  84 /**
  85  * Initialize only minimal components of XPCOM. This ensures nsThreadManager,
  86  * logging, and timers will work.
  87  */
  88 XPCOM_API(nsresult)
  89 NS_InitMinimalXPCOM();
  90
  91 /**
  92  * Shutdown XPCOM. You must call this method after you are finished
  93  * using xpcom.
  94  *
  95  * @param aServMgr          The service manager which was returned by
  96  * NS_InitXPCOM. This will release servMgr.  You may pass null.
  97  *
  98  * @return NS_OK for success;
  99  *         other error codes indicate a failure during initialisation.
 100  *
 101  * MOZ_CAN_RUN_SCRIPT_BOUNDARY for now, but really it should maybe be
 102  * MOZ_CAN_RUN_SCRIPT.
 103  */
 104 XPCOM_API(MOZ_CAN_RUN_SCRIPT_BOUNDARY nsresult)
 105 NS_ShutdownXPCOM(nsIServiceManager* aServMgr);
 106
 107 /**
 108  * Public Method to access to the service manager.
 109  *
 110  * @param aResult Interface pointer to the service manager
 111  *
 112  * @return NS_OK for success;
 113  *         other error codes indicate a failure during initialisation.
 114  */
 115 XPCOM_API(nsresult) NS_GetServiceManager(nsIServiceManager** aResult);
 116
 117 /**
 118  * Public Method to access to the component manager.
 119  *
 120  * @param aResult Interface pointer to the service
 121  *
 122  * @return NS_OK for success;
 123  *         other error codes indicate a failure during initialisation.
 124  */
 125 XPCOM_API(nsresult) NS_GetComponentManager(nsIComponentManager** aResult);
 126
 127 /**
 128  * Public Method to access to the component registration manager.
 129  *
 130  * @param aResult Interface pointer to the service
 131  *
 132  * @return NS_OK for success;
 133  *         other error codes indicate a failure during initialisation.
 134  */
 135 XPCOM_API(nsresult) NS_GetComponentRegistrar(nsIComponentRegistrar** aResult);
 136
 137 /**
 138  * Public Method to access to the memory manager.  See nsIMemory
 139  *
 140  * @param aResult Interface pointer to the memory manager
 141  *
 142  * @return NS_OK for success;
 143  *         other error codes indicate a failure during initialisation.
 144  */
 145 XPCOM_API(nsresult) NS_GetMemoryManager(nsIMemory** aResult);
 146
 147 /**
 148  * Public Method to create an instance of a nsIFile.  This function
 149  * may be called prior to NS_InitXPCOM.
 150  *
 151  *   @param aPath
 152  *       A string which specifies a full file path to a
 153  *       location.  Relative paths will be treated as an
 154  *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).
 155  *       |NS_NewNativeLocalFile|'s path must be in the
 156  *       filesystem charset.
 157  *   @param aFollowLinks
 158  *       This attribute will determine if the nsLocalFile will auto
 159  *       resolve symbolic links.  By default, this value will be false
 160  *       on all non unix systems.  On unix, this attribute is effectively
 161  *       a noop.
 162  * @param aResult Interface pointer to a new instance of an nsIFile
 163  *
 164  * @return NS_OK for success;
 165  *         other error codes indicate a failure.
 166  */
 167
 168 #ifdef __cplusplus
 169
 170 XPCOM_API(nsresult)
 171 NS_NewLocalFile(const nsAString& aPath, bool aFollowLinks, nsIFile** aResult);
 172
 173 XPCOM_API(nsresult)
 174 NS_NewNativeLocalFile(const nsACString& aPath, bool aFollowLinks,
 175                       nsIFile** aResult);
 176
 177 // Use NS_NewLocalFile if you already have a UTF-16 string.
 178 // Otherwise non-ASCII paths will break on some platforms
 179 // including Windows.
 180 class NS_ConvertUTF16toUTF8;
 181 nsresult NS_NewNativeLocalFile(const NS_ConvertUTF16toUTF8& aPath,
 182                                bool aFollowLinks, nsIFile** aResult) = delete;
 183
 184 #endif
 185
 186 /**
 187  * Support for warnings, assertions, and debugging breaks.
 188  */
 189
 190 enum {
 191   NS_DEBUG_WARNING = 0,
 192   NS_DEBUG_ASSERTION = 1,
 193   NS_DEBUG_BREAK = 2,
 194   NS_DEBUG_ABORT = 3
 195 };
 196
 197 /**
 198  * Print a runtime assertion. This function is available in both debug and
 199  * release builds.
 200  *
 201  * @note Based on the value of aSeverity and the XPCOM_DEBUG_BREAK
 202  * environment variable, this function may cause the application to
 203  * print the warning, print a stacktrace, break into a debugger, or abort
 204  * immediately.
 205  *
 206  * @param aSeverity A NS_DEBUG_* value
 207  * @param aStr   A readable error message (ASCII, may be null)
 208  * @param aExpr  The expression evaluated (may be null)
 209  * @param aFile  The source file containing the assertion (may be null)
 210  * @param aLine  The source file line number (-1 indicates no line number)
 211  */
 212 XPCOM_API(void)
 213 NS_DebugBreak(uint32_t aSeverity, const char* aStr, const char* aExpr,
 214               const char* aFile, int32_t aLine);
 215
 216 /**
 217  * Perform a stack-walk to a debugging log under various
 218  * circumstances. Used to aid debugging of leaked object graphs.
 219  *
 220  * The NS_Log* functions are available in both debug and release
 221  * builds of XPCOM, but the output will be useless unless binary
 222  * debugging symbols for all modules in the stacktrace are available.
 223  */
 224
 225 /**
 226  * By default, refcount logging is enabled at NS_InitXPCOM and
 227  * refcount statistics are printed at NS_ShutdownXPCOM. NS_LogInit and
 228  * NS_LogTerm allow applications to enable logging earlier and delay
 229  * printing of logging statistics. They should always be used as a
 230  * matched pair.
 231  */
 232 XPCOM_API(void) NS_LogInit();
 233
 234 XPCOM_API(void) NS_LogTerm();
 235
 236 #ifdef __cplusplus
 237 /**
 238  * A helper class that calls NS_LogInit in its constructor and
 239  * NS_LogTerm in its destructor.
 240  */
 241
 242 class ScopedLogging {
 243  public:
 244   ScopedLogging() { NS_LogInit(); }
 245
 246   ~ScopedLogging() { NS_LogTerm(); }
 247 };
 248 #endif
 249
 250 /**
 251  * Log construction and destruction of objects. Processing tools can use the
 252  * stacktraces printed by these functions to identify objects that are being
 253  * leaked.
 254  *
 255  * @param aPtr          A pointer to the concrete object.
 256  * @param aTypeName     The class name of the type
 257  * @param aInstanceSize The size of the type
 258  */
 259
 260 XPCOM_API(void)
 261 NS_LogCtor(void* aPtr, const char* aTypeName, uint32_t aInstanceSize);
 262
 263 XPCOM_API(void)
 264 NS_LogDtor(void* aPtr, const char* aTypeName, uint32_t aInstanceSize);
 265
 266 /**
 267  * Log a stacktrace when an XPCOM object's refcount is incremented or
 268  * decremented. Processing tools can use the stacktraces printed by these
 269  * functions to identify objects that were leaked due to XPCOM references.
 270  *
 271  * @param aPtr          A pointer to the concrete object
 272  * @param aNewRefCnt    The new reference count.
 273  * @param aTypeName     The class name of the type
 274  * @param aInstanceSize The size of the type
 275  */
 276 XPCOM_API(void)
 277 NS_LogAddRef(void* aPtr, nsrefcnt aNewRefCnt, const char* aTypeName,
 278              uint32_t aInstanceSize);
 279
 280 XPCOM_API(void)
 281 NS_LogRelease(void* aPtr, nsrefcnt aNewRefCnt, const char* aTypeName);
 282
 283 /**
 284  * Log reference counting performed by COMPtrs. Processing tools can
 285  * use the stacktraces printed by these functions to simplify reports
 286  * about leaked objects generated from the data printed by
 287  * NS_LogAddRef/NS_LogRelease.
 288  *
 289  * @param aCOMPtr the address of the COMPtr holding a strong reference
 290  * @param aObject the object being referenced by the COMPtr
 291  */
 292
 293 XPCOM_API(void) NS_LogCOMPtrAddRef(void* aCOMPtr, nsISupports* aObject);
 294
 295 XPCOM_API(void) NS_LogCOMPtrRelease(void* aCOMPtr, nsISupports* aObject);
 296
 297 /**
 298  * The XPCOM cycle collector analyzes and breaks reference cycles between
 299  * participating XPCOM objects. All objects in the cycle must implement
 300  * nsCycleCollectionParticipant to break cycles correctly.
 301  */
 302
 303 #ifdef __cplusplus
 304
 305 class nsCycleCollectionParticipant;
 306 class nsCycleCollectingAutoRefCnt;
 307
 308 XPCOM_API(void)
 309 NS_CycleCollectorSuspect3(void* aPtr, nsCycleCollectionParticipant* aCp,
 310                           nsCycleCollectingAutoRefCnt* aRefCnt,
 311                           bool* aShouldDelete);
 312
 313 XPCOM_API(void)
 314 NS_CycleCollectorSuspectUsingNursery(void* aPtr,
 315                                      nsCycleCollectionParticipant* aCp,
 316                                      nsCycleCollectingAutoRefCnt* aRefCnt,
 317                                      bool* aShouldDelete);
 318
 319 #endif
 320
 321 /**
 322  * Categories (in the category manager service) used by XPCOM:
 323  */
 324
 325 /**
 326  * A category which is read after component registration but before
 327  * the "xpcom-startup" notifications. Each category entry is treated
 328  * as the contract ID of a service which implements
 329  * nsIDirectoryServiceProvider. Each directory service provider is
 330  * installed in the global directory service.
 331  */
 332 #define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
 333
 334 /**
 335  * A category which is read after component registration but before
 336  * NS_InitXPCOM returns. Each category entry is treated as the contractID of
 337  * a service: each service is instantiated, and if it implements nsIObserver
 338  * the nsIObserver.observe method is called with the "xpcom-startup" topic.
 339  */
 340 #define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
 341
 342 /**
 343  * Observer topics (in the observer service) used by XPCOM:
 344  */
 345
 346 /**
 347  * At XPCOM startup after component registration is complete, the
 348  * following topic is notified. In order to receive this notification,
 349  * component must register their contract ID in the category manager,
 350  *
 351  * @see NS_XPCOM_STARTUP_CATEGORY
 352  */
 353 #define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
 354
 355 /**
 356  * At XPCOM shutdown, this topic is notified just before "xpcom-shutdown".
 357  * Components should only use this to mark themselves as 'being destroyed'.
 358  * Nothing should be dispatched to any event loop.
 359  */
 360 #define NS_XPCOM_WILL_SHUTDOWN_OBSERVER_ID "xpcom-will-shutdown"
 361
 362 /**
 363  * At XPCOM shutdown, this topic is notified. All components must
 364  * release any interface references to objects in other modules when
 365  * this topic is notified.
 366  */
 367 #define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
 368
 369 /**
 370  * This topic is notified when an entry was added to a category in the
 371  * category manager. The subject of the notification will be the name of
 372  * the added entry as an nsISupportsCString, and the data will be the
 373  * name of the category. The notification will occur on the main thread.
 374  */
 375 #define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID "xpcom-category-entry-added"
 376
 377 /**
 378  * This topic is notified when an entry was removed from a category in the
 379  * category manager. The subject of the notification will be the name of
 380  * the removed entry as an nsISupportsCString, and the data will be the
 381  * name of the category. The notification will occur on the main thread.
 382  */
 383 #define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID \
 384   "xpcom-category-entry-removed"
 385
 386 /**
 387  * This topic is notified when an a category was cleared in the category
 388  * manager. The subject of the notification will be the category manager,
 389  * and the data will be the name of the cleared category.
 390  * The notification will occur on the main thread.
 391  */
 392 #define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
 393
 394 XPCOM_API(nsresult) NS_GetDebug(nsIDebug2** aResult);
 395
 396 #endif