xpcom/build/nsXPCOM.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Benjamin Smedberg <benjamin@smedbergs.us>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef nsXPCOM_h__
  40 #define nsXPCOM_h__
  41
  42 /* Map frozen functions to private symbol names if not using strict API. */
  43 #ifdef MOZILLA_INTERNAL_API
  44 # define NS_InitXPCOM2               NS_InitXPCOM2_P
  45 # define NS_InitXPCOM3               NS_InitXPCOM3_P
  46 # define NS_ShutdownXPCOM            NS_ShutdownXPCOM_P
  47 # define NS_GetServiceManager        NS_GetServiceManager_P
  48 # define NS_GetComponentManager      NS_GetComponentManager_P
  49 # define NS_GetComponentRegistrar    NS_GetComponentRegistrar_P
  50 # define NS_GetMemoryManager         NS_GetMemoryManager_P
  51 # define NS_NewLocalFile             NS_NewLocalFile_P
  52 # define NS_NewNativeLocalFile       NS_NewNativeLocalFile_P
  53 # define NS_GetDebug                 NS_GetDebug_P
  54 # define NS_GetTraceRefcnt           NS_GetTraceRefcnt_P
  55 # define NS_Alloc                    NS_Alloc_P
  56 # define NS_Realloc                  NS_Realloc_P
  57 # define NS_Free                     NS_Free_P
  58 # define NS_DebugBreak               NS_DebugBreak_P
  59 # define NS_LogInit                  NS_LogInit_P
  60 # define NS_LogTerm                  NS_LogTerm_P
  61 # define NS_LogAddRef                NS_LogAddRef_P
  62 # define NS_LogRelease               NS_LogRelease_P
  63 # define NS_LogCtor                  NS_LogCtor_P
  64 # define NS_LogDtor                  NS_LogDtor_P
  65 # define NS_LogCOMPtrAddRef          NS_LogCOMPtrAddRef_P
  66 # define NS_LogCOMPtrRelease         NS_LogCOMPtrRelease_P
  67 # define NS_CycleCollectorSuspect    NS_CycleCollectorSuspect_P
  68 # define NS_CycleCollectorForget     NS_CycleCollectorForget_P
  69 #endif
  70
  71 #include "nscore.h"
  72 #include "nsXPCOMCID.h"
  73
  74 #ifdef __cplusplus
  75 #define DECL_CLASS(c) class c
  76 #else
  77 #define DECL_CLASS(c) typedef struct c c
  78 #endif
  79
  80 DECL_CLASS(nsAString);
  81 DECL_CLASS(nsACString);
  82
  83 DECL_CLASS(nsISupports);
  84 DECL_CLASS(nsIModule);
  85 DECL_CLASS(nsIComponentManager);
  86 DECL_CLASS(nsIComponentRegistrar);
  87 DECL_CLASS(nsIServiceManager);
  88 DECL_CLASS(nsIFile);
  89 DECL_CLASS(nsILocalFile);
  90 DECL_CLASS(nsIDirectoryServiceProvider);
  91 DECL_CLASS(nsIMemory);
  92 DECL_CLASS(nsIDebug);
  93 DECL_CLASS(nsITraceRefcnt);
  94
  95 /**
  96  * Every XPCOM component implements this function signature, which is the
  97  * only entrypoint XPCOM uses to the function.
  98  *
  99  * @status FROZEN
 100  */
 101 typedef nsresult (PR_CALLBACK *nsGetModuleProc)(nsIComponentManager *aCompMgr,
 102                                                 nsIFile* location,
 103                                                 nsIModule** return_cobj);
 104
 105 /**
 106  * Initialises XPCOM. You must call one of the NS_InitXPCOM methods
 107  * before proceeding to use xpcom. The one exception is that you may
 108  * call NS_NewLocalFile to create a nsIFile.
 109  *
 110  * @status FROZEN
 111  *
 112  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE>
 113  *       to create the file object you supply as the bin directory path in this
 114  *       call. The function may be safely called before the rest of XPCOM or
 115  *       embedding has been initialised.
 116  *
 117  * @param result           The service manager.  You may pass null.
 118  *
 119  * @param binDirectory     The directory containing the component
 120  *                         registry and runtime libraries;
 121  *                         or use <CODE>nsnull</CODE> to use the working
 122  *                         directory.
 123  *
 124  * @param appFileLocationProvider The object to be used by Gecko that specifies
 125  *                         to Gecko where to find profiles, the component
 126  *                         registry preferences and so on; or use
 127  *                         <CODE>nsnull</CODE> for the default behaviour.
 128  *
 129  * @see NS_NewLocalFile
 130  * @see nsILocalFile
 131  * @see nsIDirectoryServiceProvider
 132  *
 133  * @return NS_OK for success;
 134  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
 135  *         which can happen if XPCOM is reloaded, but did not completly
 136  *         shutdown. Other error codes indicate a failure during
 137  *         initialisation.
 138  */
 139 XPCOM_API(nsresult)
 140 NS_InitXPCOM2(nsIServiceManager* *result,
 141               nsIFile* binDirectory,
 142               nsIDirectoryServiceProvider* appFileLocationProvider);
 143
 144 /**
 145  * Some clients of XPCOM have statically linked components (not dynamically
 146  * loaded component DLLs), which can be passed to NS_InitXPCOM3 using this
 147  * structure.
 148  *
 149  * @status FROZEN
 150  */
 151 typedef struct nsStaticModuleInfo {
 152   const char      *name;
 153   nsGetModuleProc  getModule;
 154 } nsStaticModuleInfo;
 155
 156 /**
 157  * Initialises XPCOM with static components. You must call one of the
 158  * NS_InitXPCOM methods before proceeding to use xpcom. The one
 159  * exception is that you may call NS_NewLocalFile to create a nsIFile.
 160  *
 161  * @status FROZEN
 162  *
 163  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE>
 164  *       to create the file object you supply as the bin directory path in this
 165  *       call. The function may be safely called before the rest of XPCOM or
 166  *       embedding has been initialised.
 167  *
 168  * @param result           The service manager.  You may pass null.
 169  *
 170  * @param binDirectory     The directory containing the component
 171  *                         registry and runtime libraries;
 172  *                         or use <CODE>nsnull</CODE> to use the working
 173  *                         directory.
 174  *
 175  * @param appFileLocationProvider The object to be used by Gecko that specifies
 176  *                         to Gecko where to find profiles, the component
 177  *                         registry preferences and so on; or use
 178  *                         <CODE>nsnull</CODE> for the default behaviour.
 179  *
 180  * @param staticComponents An array of static components. Passing null causes
 181  *                         default (builtin) components to be registered, if
 182  *                         present.
 183  * @param componentCount   Number of elements in staticComponents
 184  *
 185  * @see NS_NewLocalFile
 186  * @see nsILocalFile
 187  * @see nsIDirectoryServiceProvider
 188  * @see XRE_GetStaticComponents
 189  *
 190  * @return NS_OK for success;
 191  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
 192  *         which can happen if XPCOM is reloaded, but did not completly
 193  *         shutdown. Other error codes indicate a failure during
 194  *         initialisation.
 195  */
 196 XPCOM_API(nsresult)
 197 NS_InitXPCOM3(nsIServiceManager* *result,
 198               nsIFile* binDirectory,
 199               nsIDirectoryServiceProvider* appFileLocationProvider,
 200               nsStaticModuleInfo const *staticComponents,
 201               PRUint32 componentCount);
 202
 203 /**
 204  * Shutdown XPCOM. You must call this method after you are finished
 205  * using xpcom.
 206  *
 207  * @status FROZEN
 208  *
 209  * @param servMgr           The service manager which was returned by NS_InitXPCOM.
 210  *                          This will release servMgr.  You may pass null.
 211  *
 212  * @return NS_OK for success;
 213  *         other error codes indicate a failure during initialisation.
 214  *
 215  */
 216 XPCOM_API(nsresult)
 217 NS_ShutdownXPCOM(nsIServiceManager* servMgr);
 218
 219
 220 /**
 221  * Public Method to access to the service manager.
 222  *
 223  * @status FROZEN
 224  * @param result Interface pointer to the service manager
 225  *
 226  * @return NS_OK for success;
 227  *         other error codes indicate a failure during initialisation.
 228  *
 229  */
 230 XPCOM_API(nsresult)
 231 NS_GetServiceManager(nsIServiceManager* *result);
 232
 233 /**
 234  * Public Method to access to the component manager.
 235  *
 236  * @status FROZEN
 237  * @param result Interface pointer to the service
 238  *
 239  * @return NS_OK for success;
 240  *         other error codes indicate a failure during initialisation.
 241  *
 242  */
 243 XPCOM_API(nsresult)
 244 NS_GetComponentManager(nsIComponentManager* *result);
 245
 246 /**
 247  * Public Method to access to the component registration manager.
 248  *
 249  * @status FROZEN
 250  * @param result Interface pointer to the service
 251  *
 252  * @return NS_OK for success;
 253  *         other error codes indicate a failure during initialisation.
 254  *
 255  */
 256 XPCOM_API(nsresult)
 257 NS_GetComponentRegistrar(nsIComponentRegistrar* *result);
 258
 259 /**
 260  * Public Method to access to the memory manager.  See nsIMemory
 261  *
 262  * @status FROZEN
 263  * @param result Interface pointer to the memory manager
 264  *
 265  * @return NS_OK for success;
 266  *         other error codes indicate a failure during initialisation.
 267  *
 268  */
 269 XPCOM_API(nsresult)
 270 NS_GetMemoryManager(nsIMemory* *result);
 271
 272 /**
 273  * Public Method to create an instance of a nsILocalFile.  This function
 274  * may be called prior to NS_InitXPCOM.
 275  *
 276  * @status FROZEN
 277  *
 278  *   @param path
 279  *       A string which specifies a full file path to a
 280  *       location.  Relative paths will be treated as an
 281  *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).
 282  *       |NS_NewNativeLocalFile|'s path must be in the
 283  *       filesystem charset.
 284  *   @param followLinks
 285  *       This attribute will determine if the nsLocalFile will auto
 286  *       resolve symbolic links.  By default, this value will be false
 287  *       on all non unix systems.  On unix, this attribute is effectively
 288  *       a noop.
 289  * @param result Interface pointer to a new instance of an nsILocalFile
 290  *
 291  * @return NS_OK for success;
 292  *         other error codes indicate a failure.
 293  */
 294
 295 #ifdef __cplusplus
 296
 297 XPCOM_API(nsresult)
 298 NS_NewLocalFile(const nsAString &path,
 299                 PRBool followLinks,
 300                 nsILocalFile* *result);
 301
 302 XPCOM_API(nsresult)
 303 NS_NewNativeLocalFile(const nsACString &path,
 304                       PRBool followLinks,
 305                       nsILocalFile* *result);
 306
 307 #endif
 308
 309 /**
 310  * Allocates a block of memory of a particular size. If the memory cannot
 311  * be allocated (because of an out-of-memory condition), null is returned.
 312  *
 313  * @status FROZEN
 314  *
 315  * @param size   The size of the block to allocate
 316  * @result       The block of memory
 317  * @note         This function is thread-safe.
 318  */
 319 XPCOM_API(void*)
 320 NS_Alloc(PRSize size);
 321
 322 /**
 323  * Reallocates a block of memory to a new size.
 324  *
 325  * @status FROZEN
 326  *
 327  * @param ptr     The block of memory to reallocate. This block must originally
 328                   have been allocated by NS_Alloc or NS_Realloc
 329  * @param size    The new size. If 0, frees the block like NS_Free
 330  * @result        The reallocated block of memory
 331  * @note          This function is thread-safe.
 332  *
 333  * If ptr is null, this function behaves like NS_Alloc.
 334  * If s is the size of the block to which ptr points, the first min(s, size)
 335  * bytes of ptr's block are copied to the new block. If the allocation
 336  * succeeds, ptr is freed and a pointer to the new block is returned. If the
 337  * allocation fails, ptr is not freed and null is returned. The returned
 338  * value may be the same as ptr.
 339  */
 340 XPCOM_API(void*)
 341 NS_Realloc(void* ptr, PRSize size);
 342
 343 /**
 344  * Frees a block of memory. Null is a permissible value, in which case no
 345  * action is taken.
 346  *
 347  * @status FROZEN
 348  *
 349  * @param ptr   The block of memory to free. This block must originally have
 350  *              been allocated by NS_Alloc or NS_Realloc
 351  * @note        This function is thread-safe.
 352  */
 353 XPCOM_API(void)
 354 NS_Free(void* ptr);
 355
 356 /**
 357  * Support for warnings, assertions, and debugging breaks.
 358  */
 359
 360 enum {
 361     NS_DEBUG_WARNING = 0,
 362     NS_DEBUG_ASSERTION = 1,
 363     NS_DEBUG_BREAK = 2,
 364     NS_DEBUG_ABORT = 3
 365 };
 366
 367 /**
 368  * Print a runtime assertion. This function is available in both debug and
 369  * release builds.
 370  *
 371  * @note Based on the value of aSeverity and the XPCOM_DEBUG_BREAK
 372  * environment variable, this function may cause the application to
 373  * print the warning, print a stacktrace, break into a debugger, or abort
 374  * immediately.
 375  *
 376  * @param aSeverity A NS_DEBUG_* value
 377  * @param aStr   A readable error message (ASCII, may be null)
 378  * @param aExpr  The expression evaluated (may be null)
 379  * @param aFile  The source file containing the assertion (may be null)
 380  * @param aLine  The source file line number (-1 indicates no line number)
 381  */
 382 XPCOM_API(void)
 383 NS_DebugBreak(PRUint32 aSeverity,
 384               const char *aStr, const char *aExpr,
 385               const char *aFile, PRInt32 aLine);
 386
 387 /**
 388  * Perform a stack-walk to a debugging log under various
 389  * circumstances. Used to aid debugging of leaked object graphs.
 390  *
 391  * The NS_Log* functions are available in both debug and release
 392  * builds of XPCOM, but the output will be useless unless binary
 393  * debugging symbols for all modules in the stacktrace are available.
 394  */
 395
 396 /**
 397  * By default, refcount logging is enabled at NS_InitXPCOM and
 398  * refcount statistics are printed at NS_ShutdownXPCOM. NS_LogInit and
 399  * NS_LogTerm allow applications to enable logging earlier and delay
 400  * printing of logging statistics. They should always be used as a
 401  * matched pair.
 402  */
 403 XPCOM_API(void)
 404 NS_LogInit();
 405
 406 XPCOM_API(void)
 407 NS_LogTerm();
 408
 409 /**
 410  * Log construction and destruction of objects. Processing tools can use the
 411  * stacktraces printed by these functions to identify objects that are being
 412  * leaked.
 413  *
 414  * @param aPtr          A pointer to the concrete object.
 415  * @param aTypeName     The class name of the type
 416  * @param aInstanceSize The size of the type
 417  */
 418
 419 XPCOM_API(void)
 420 NS_LogCtor(void *aPtr, const char *aTypeName, PRUint32 aInstanceSize);
 421
 422 XPCOM_API(void)
 423 NS_LogDtor(void *aPtr, const char *aTypeName, PRUint32 aInstanceSize);
 424
 425 /**
 426  * Log a stacktrace when an XPCOM object's refcount is incremented or
 427  * decremented. Processing tools can use the stacktraces printed by these
 428  * functions to identify objects that were leaked due to XPCOM references.
 429  *
 430  * @param aPtr          A pointer to the concrete object
 431  * @param aNewRefCnt    The new reference count.
 432  * @param aTypeName     The class name of the type
 433  * @param aInstanceSize The size of the type
 434  */
 435 XPCOM_API(void)
 436 NS_LogAddRef(void *aPtr, nsrefcnt aNewRefCnt,
 437              const char *aTypeName, PRUint32 aInstanceSize);
 438
 439 XPCOM_API(void)
 440 NS_LogRelease(void *aPtr, nsrefcnt aNewRefCnt, const char *aTypeName);
 441
 442 /**
 443  * Log reference counting performed by COMPtrs. Processing tools can
 444  * use the stacktraces printed by these functions to simplify reports
 445  * about leaked objects generated from the data printed by
 446  * NS_LogAddRef/NS_LogRelease.
 447  *
 448  * @param aCOMPtr the address of the COMPtr holding a strong reference
 449  * @param aObject the object being referenced by the COMPtr
 450  */
 451
 452 XPCOM_API(void)
 453 NS_LogCOMPtrAddRef(void *aCOMPtr, nsISupports *aObject);
 454
 455 XPCOM_API(void)
 456 NS_LogCOMPtrRelease(void *aCOMPtr, nsISupports *aObject);
 457
 458 /**
 459  * The XPCOM cycle collector analyzes and breaks reference cycles between
 460  * participating XPCOM objects. All objects in the cycle must implement
 461  * nsCycleCollectionParticipant to break cycles correctly.
 462  */
 463 XPCOM_API(PRBool)
 464 NS_CycleCollectorSuspect(nsISupports *n);
 465
 466 XPCOM_API(PRBool)
 467 NS_CycleCollectorForget(nsISupports *n);
 468
 469 /**
 470  * Categories (in the category manager service) used by XPCOM:
 471  */
 472
 473 /**
 474  * A category which is read after component registration but before
 475  * the "xpcom-startup" notifications. Each category entry is treated
 476  * as the contract ID of a service which implements
 477  * nsIDirectoryServiceProvider. Each directory service provider is
 478  * installed in the global directory service.
 479  *
 480  * @status FROZEN
 481  */
 482 #define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
 483
 484 /**
 485  * A category which is read after component registration but before
 486  * NS_InitXPCOM returns. Each category entry is treated as the contractID of
 487  * a service: each service is instantiated, and if it implements nsIObserver
 488  * the nsIObserver.observe method is called with the "xpcom-startup" topic.
 489  *
 490  * @status FROZEN
 491  */
 492 #define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
 493
 494
 495 /**
 496  * Observer topics (in the observer service) used by XPCOM:
 497  */
 498
 499 /**
 500  * At XPCOM startup after component registration is complete, the
 501  * following topic is notified. In order to receive this notification,
 502  * component must register their contract ID in the category manager,
 503  *
 504  * @see NS_XPCOM_STARTUP_CATEGORY
 505  * @status FROZEN
 506  */
 507 #define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
 508
 509 /**
 510  * At XPCOM shutdown, this topic is notified. All components must
 511  * release any interface references to objects in other modules when
 512  * this topic is notified.
 513  *
 514  * @status FROZEN
 515  */
 516 #define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
 517
 518 /**
 519  * This topic is notified when an entry was added to a category in the
 520  * category manager. The subject of the notification will be the name of
 521  * the added entry as an nsISupportsCString, and the data will be the
 522  * name of the category. The notification will occur on the main thread.
 523  *
 524  * @status FROZEN
 525  */
 526 #define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID \
 527   "xpcom-category-entry-added"
 528
 529 /**
 530  * This topic is notified when an entry was removed from a category in the
 531  * category manager. The subject of the notification will be the name of
 532  * the removed entry as an nsISupportsCString, and the data will be the
 533  * name of the category. The notification will occur on the main thread.
 534  *
 535  * @status FROZEN
 536  */
 537 #define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID \
 538   "xpcom-category-entry-removed"
 539
 540 /**
 541  * This topic is notified when an a category was cleared in the category
 542  * manager. The subject of the notification will be the category manager,
 543  * and the data will be the name of the cleared category.
 544  * The notification will occur on the main thread.
 545  *
 546  * @status FROZEN
 547  */
 548 #define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
 549
 550 XPCOM_API(nsresult)
 551 NS_GetDebug(nsIDebug* *result);
 552
 553 XPCOM_API(nsresult)
 554 NS_GetTraceRefcnt(nsITraceRefcnt* *result);
 555
 556 #endif