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