xpcom/build/nsXPCOM.h

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