Classes | Defines | Typedefs | Enumerations | Functions

nsXPCOM.h File Reference

#include "nscore.h"
#include "nsXPCOMCID.h"
Include dependency graph for nsXPCOM.h:
This graph shows which files directly or indirectly include this file:

Classes

struct  nsStaticModuleInfo
 Some clients of XPCOM have statically linked components (not dynamically loaded component DLLs), which can be passed to NS_InitXPCOM3 using this structure. More...

Defines

#define DECL_CLASS(c)   typedef struct c c
#define DECL_STRUCT(c)   typedef struct c c
#define XPCOM_DIRECTORY_PROVIDER_CATEGORY   "xpcom-directory-providers"
 Categories (in the category manager service) used by XPCOM:
#define NS_XPCOM_STARTUP_CATEGORY   "xpcom-startup"
 A category which is read after component registration but before NS_InitXPCOM returns.
#define NS_XPCOM_STARTUP_OBSERVER_ID   "xpcom-startup"
 Observer topics (in the observer service) used by XPCOM:
#define NS_XPCOM_WILL_SHUTDOWN_OBSERVER_ID   "xpcom-will-shutdown"
 At XPCOM shutdown, this topic is notified just before "xpcom-shutdown".
#define NS_XPCOM_SHUTDOWN_OBSERVER_ID   "xpcom-shutdown"
 At XPCOM shutdown, this topic is notified.
#define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID   "xpcom-category-entry-added"
 This topic is notified when an entry was added to a category in the category manager.
#define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID   "xpcom-category-entry-removed"
 This topic is notified when an entry was removed from a category in the category manager.
#define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID   "xpcom-category-cleared"
 This topic is notified when an a category was cleared in the category manager.

Typedefs

typedef struct nsAString nsAString
typedef struct nsACString nsACString
typedef struct nsISupports nsISupports
typedef struct nsIModule nsIModule
typedef struct nsIComponentManager nsIComponentManager
typedef struct
nsIComponentRegistrar 
nsIComponentRegistrar
typedef struct nsIServiceManager nsIServiceManager
typedef struct nsIFile nsIFile
typedef struct nsILocalFile nsILocalFile
typedef struct
nsIDirectoryServiceProvider 
nsIDirectoryServiceProvider
typedef struct nsIMemory nsIMemory
typedef struct nsIDebug nsIDebug
typedef struct nsITraceRefcnt nsITraceRefcnt
typedef struct nsPurpleBufferEntry nsPurpleBufferEntry
typedef nsresult(* nsGetModuleProc )(nsIComponentManager *aCompMgr, nsIFile *location, nsIModule **return_cobj)
 Every XPCOM component implements this function signature, which is the only entrypoint XPCOM uses to the function.
typedef struct nsStaticModuleInfo nsStaticModuleInfo
 Some clients of XPCOM have statically linked components (not dynamically loaded component DLLs), which can be passed to NS_InitXPCOM3 using this structure.

Enumerations

enum  { NS_DEBUG_WARNING = 0, NS_DEBUG_ASSERTION = 1, NS_DEBUG_BREAK = 2, NS_DEBUG_ABORT = 3 }
 

Support for warnings, assertions, and debugging breaks.

More...

Functions

nsresult NS_InitXPCOM2 (nsIServiceManager **result, nsIFile *binDirectory, nsIDirectoryServiceProvider *appFileLocationProvider)
 Initialises XPCOM.
nsresult NS_InitXPCOM3 (nsIServiceManager **result, nsIFile *binDirectory, nsIDirectoryServiceProvider *appFileLocationProvider, nsStaticModuleInfo const *staticComponents, PRUint32 componentCount)
 Initialises XPCOM with static components.
nsresult NS_ShutdownXPCOM (nsIServiceManager *servMgr)
 Shutdown XPCOM.
nsresult NS_GetServiceManager (nsIServiceManager **result)
 Public Method to access to the service manager.
nsresult NS_GetComponentManager (nsIComponentManager **result)
 Public Method to access to the component manager.
nsresult NS_GetComponentRegistrar (nsIComponentRegistrar **result)
 Public Method to access to the component registration manager.
nsresult NS_GetMemoryManager (nsIMemory **result)
 Public Method to access to the memory manager.
void * NS_Alloc (PRSize size)
 Public Method to create an instance of a nsILocalFile.
void * NS_Realloc (void *ptr, PRSize size)
 Reallocates a block of memory to a new size.
void NS_Free (void *ptr)
 Frees a block of memory.
void NS_DebugBreak (PRUint32 aSeverity, const char *aStr, const char *aExpr, const char *aFile, PRInt32 aLine)
 Print a runtime assertion.
void NS_LogInit ()
 Perform a stack-walk to a debugging log under various circumstances.
void NS_LogTerm ()
void NS_LogCtor (void *aPtr, const char *aTypeName, PRUint32 aInstanceSize)
 Log construction and destruction of objects.
void NS_LogDtor (void *aPtr, const char *aTypeName, PRUint32 aInstanceSize)
void NS_LogAddRef (void *aPtr, nsrefcnt aNewRefCnt, const char *aTypeName, PRUint32 aInstanceSize)
 Log a stacktrace when an XPCOM object's refcount is incremented or decremented.
void NS_LogRelease (void *aPtr, nsrefcnt aNewRefCnt, const char *aTypeName)
void NS_LogCOMPtrAddRef (void *aCOMPtr, nsISupports *aObject)
 Log reference counting performed by COMPtrs.
void NS_LogCOMPtrRelease (void *aCOMPtr, nsISupports *aObject)
PRBool NS_CycleCollectorSuspect (nsISupports *n)
 The XPCOM cycle collector analyzes and breaks reference cycles between participating XPCOM objects.
PRBool NS_CycleCollectorForget (nsISupports *n)
nsPurpleBufferEntryNS_CycleCollectorSuspect2 (nsISupports *n)
PRBool NS_CycleCollectorForget2 (nsPurpleBufferEntry *e)
nsresult NS_GetDebug (nsIDebug **result)
nsresult NS_GetTraceRefcnt (nsITraceRefcnt **result)

Define Documentation

#define DECL_CLASS (   c  )     typedef struct c c
#define DECL_STRUCT (   c  )     typedef struct c c
#define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID   "xpcom-category-cleared"

This topic is notified when an a category was cleared in the category manager.

The subject of the notification will be the category manager, and the data will be the name of the cleared category. The notification will occur on the main thread.

Status:
FROZEN
#define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID   "xpcom-category-entry-added"

This topic is notified when an entry was added to a category in the category manager.

The subject of the notification will be the name of the added entry as an nsISupportsCString, and the data will be the name of the category. The notification will occur on the main thread.

Status:
FROZEN
#define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID   "xpcom-category-entry-removed"

This topic is notified when an entry was removed from a category in the category manager.

The subject of the notification will be the name of the removed entry as an nsISupportsCString, and the data will be the name of the category. The notification will occur on the main thread.

Status:
FROZEN
#define NS_XPCOM_SHUTDOWN_OBSERVER_ID   "xpcom-shutdown"

At XPCOM shutdown, this topic is notified.

All components must release any interface references to objects in other modules when this topic is notified.

Status:
FROZEN
#define NS_XPCOM_STARTUP_CATEGORY   "xpcom-startup"

A category which is read after component registration but before NS_InitXPCOM returns.

Each category entry is treated as the contractID of a service: each service is instantiated, and if it implements nsIObserver the nsIObserver.observe method is called with the "xpcom-startup" topic.

Status:
FROZEN
#define NS_XPCOM_STARTUP_OBSERVER_ID   "xpcom-startup"

Observer topics (in the observer service) used by XPCOM:

At XPCOM startup after component registration is complete, the following topic is notified. In order to receive this notification, component must register their contract ID in the category manager,

See also:
NS_XPCOM_STARTUP_CATEGORY
Status:
FROZEN
#define NS_XPCOM_WILL_SHUTDOWN_OBSERVER_ID   "xpcom-will-shutdown"

At XPCOM shutdown, this topic is notified just before "xpcom-shutdown".

Components should only use this to mark themselves as 'being destroyed'. Nothing should be dispatched to any event loop.

#define XPCOM_DIRECTORY_PROVIDER_CATEGORY   "xpcom-directory-providers"

Categories (in the category manager service) used by XPCOM:

A category which is read after component registration but before the "xpcom-startup" notifications. Each category entry is treated as the contract ID of a service which implements nsIDirectoryServiceProvider. Each directory service provider is installed in the global directory service.

Status:
FROZEN

Typedef Documentation

typedef struct nsACString nsACString
typedef struct nsAString nsAString
typedef nsresult(* nsGetModuleProc)(nsIComponentManager *aCompMgr, nsIFile *location, nsIModule **return_cobj)

Every XPCOM component implements this function signature, which is the only entrypoint XPCOM uses to the function.

Status:
FROZEN
typedef struct nsIDebug nsIDebug
typedef struct nsIFile nsIFile
typedef struct nsILocalFile nsILocalFile
typedef struct nsIMemory nsIMemory
typedef struct nsIModule nsIModule
typedef struct nsISupports nsISupports

Some clients of XPCOM have statically linked components (not dynamically loaded component DLLs), which can be passed to NS_InitXPCOM3 using this structure.

Status:
FROZEN

Enumeration Type Documentation

anonymous enum

Support for warnings, assertions, and debugging breaks.

Enumerator:
NS_DEBUG_WARNING 
NS_DEBUG_ASSERTION 
NS_DEBUG_BREAK 
NS_DEBUG_ABORT 

Function Documentation

void* NS_Alloc ( PRSize  size  ) 

Public Method to create an instance of a nsILocalFile.

This function may be called prior to NS_InitXPCOM.

Status:
FROZEN
Parameters:
path A string which specifies a full file path to a location. Relative paths will be treated as an error (NS_ERROR_FILE_UNRECOGNIZED_PATH). |NS_NewNativeLocalFile|'s path must be in the filesystem charset.
followLinks This attribute will determine if the nsLocalFile will auto resolve symbolic links. By default, this value will be false on all non unix systems. On unix, this attribute is effectively a noop.
result Interface pointer to a new instance of an nsILocalFile
Returns:
NS_OK for success; other error codes indicate a failure. Allocates a block of memory of a particular size. If the memory cannot be allocated (because of an out-of-memory condition), null is returned.
Status:
FROZEN
Parameters:
size The size of the block to allocate
Returns:
The block of memory
Note:
This function is thread-safe.
PRBool NS_CycleCollectorForget ( nsISupports n  ) 
PRBool NS_CycleCollectorForget2 ( nsPurpleBufferEntry e  ) 
PRBool NS_CycleCollectorSuspect ( nsISupports n  ) 

The XPCOM cycle collector analyzes and breaks reference cycles between participating XPCOM objects.

All objects in the cycle must implement nsCycleCollectionParticipant to break cycles correctly.

The first two functions below exist only to support binary components that were compiled for older XPCOM versions.

nsPurpleBufferEntry* NS_CycleCollectorSuspect2 ( nsISupports n  ) 
void NS_DebugBreak ( PRUint32  aSeverity,
const char *  aStr,
const char *  aExpr,
const char *  aFile,
PRInt32  aLine 
)

Print a runtime assertion.

This function is available in both debug and release builds.

Note:
Based on the value of aSeverity and the XPCOM_DEBUG_BREAK environment variable, this function may cause the application to print the warning, print a stacktrace, break into a debugger, or abort immediately.
Parameters:
aSeverity A NS_DEBUG_* value
aStr A readable error message (ASCII, may be null)
aExpr The expression evaluated (may be null)
aFile The source file containing the assertion (may be null)
aLine The source file line number (-1 indicates no line number)
void NS_Free ( void *  ptr  ) 

Frees a block of memory.

Null is a permissible value, in which case no action is taken.

Status:
FROZEN
Parameters:
ptr The block of memory to free. This block must originally have been allocated by NS_Alloc or NS_Realloc
Note:
This function is thread-safe.
nsresult NS_GetComponentManager ( nsIComponentManager **  result  ) 

Public Method to access to the component manager.

Status:
FROZEN
Parameters:
result Interface pointer to the service
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.
nsresult NS_GetComponentRegistrar ( nsIComponentRegistrar **  result  ) 

Public Method to access to the component registration manager.

Status:
FROZEN
Parameters:
result Interface pointer to the service
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.
nsresult NS_GetDebug ( nsIDebug **  result  ) 
nsresult NS_GetMemoryManager ( nsIMemory **  result  ) 

Public Method to access to the memory manager.

See nsIMemory

Status:
FROZEN
Parameters:
result Interface pointer to the memory manager
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.
nsresult NS_GetServiceManager ( nsIServiceManager **  result  ) 

Public Method to access to the service manager.

Status:
FROZEN
Parameters:
result Interface pointer to the service manager
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.
nsresult NS_GetTraceRefcnt ( nsITraceRefcnt **  result  ) 
nsresult NS_InitXPCOM2 ( nsIServiceManager **  result,
nsIFile binDirectory,
nsIDirectoryServiceProvider appFileLocationProvider 
)

Initialises XPCOM.

You must call one of the NS_InitXPCOM methods before proceeding to use xpcom. The one exception is that you may call NS_NewLocalFile to create a nsIFile.

Status:
FROZEN
Note:
Use NS_NewLocalFile or NS_NewNativeLocalFile to create the file object you supply as the bin directory path in this call. The function may be safely called before the rest of XPCOM or embedding has been initialised.
Parameters:
result The service manager. You may pass null.
binDirectory The directory containing the component registry and runtime libraries; or use nsnull to use the working directory.
appFileLocationProvider The object to be used by Gecko that specifies to Gecko where to find profiles, the component registry preferences and so on; or use nsnull for the default behaviour.
See also:
NS_NewLocalFile
nsILocalFile
nsIDirectoryServiceProvider
Returns:
NS_OK for success; NS_ERROR_NOT_INITIALIZED if static globals were not initialized, which can happen if XPCOM is reloaded, but did not completly shutdown. Other error codes indicate a failure during initialisation.
nsresult NS_InitXPCOM3 ( nsIServiceManager **  result,
nsIFile binDirectory,
nsIDirectoryServiceProvider appFileLocationProvider,
nsStaticModuleInfo const *  staticComponents,
PRUint32  componentCount 
)

Initialises XPCOM with static components.

You must call one of the NS_InitXPCOM methods before proceeding to use xpcom. The one exception is that you may call NS_NewLocalFile to create a nsIFile.

Status:
FROZEN
Note:
Use NS_NewLocalFile or NS_NewNativeLocalFile to create the file object you supply as the bin directory path in this call. The function may be safely called before the rest of XPCOM or embedding has been initialised.
Parameters:
result The service manager. You may pass null.
binDirectory The directory containing the component registry and runtime libraries; or use nsnull to use the working directory.
appFileLocationProvider The object to be used by Gecko that specifies to Gecko where to find profiles, the component registry preferences and so on; or use nsnull for the default behaviour.
staticComponents An array of static components. Passing null causes default (builtin) components to be registered, if present.
componentCount Number of elements in staticComponents
See also:
NS_NewLocalFile
nsILocalFile
nsIDirectoryServiceProvider
XRE_GetStaticComponents
Returns:
NS_OK for success; NS_ERROR_NOT_INITIALIZED if static globals were not initialized, which can happen if XPCOM is reloaded, but did not completly shutdown. Other error codes indicate a failure during initialisation.
void NS_LogAddRef ( void *  aPtr,
nsrefcnt  aNewRefCnt,
const char *  aTypeName,
PRUint32  aInstanceSize 
)

Log a stacktrace when an XPCOM object's refcount is incremented or decremented.

Processing tools can use the stacktraces printed by these functions to identify objects that were leaked due to XPCOM references.

Parameters:
aPtr A pointer to the concrete object
aNewRefCnt The new reference count.
aTypeName The class name of the type
aInstanceSize The size of the type
void NS_LogCOMPtrAddRef ( void *  aCOMPtr,
nsISupports aObject 
)

Log reference counting performed by COMPtrs.

Processing tools can use the stacktraces printed by these functions to simplify reports about leaked objects generated from the data printed by NS_LogAddRef/NS_LogRelease.

Parameters:
aCOMPtr the address of the COMPtr holding a strong reference
aObject the object being referenced by the COMPtr
void NS_LogCOMPtrRelease ( void *  aCOMPtr,
nsISupports aObject 
)
void NS_LogCtor ( void *  aPtr,
const char *  aTypeName,
PRUint32  aInstanceSize 
)

Log construction and destruction of objects.

Processing tools can use the stacktraces printed by these functions to identify objects that are being leaked.

Parameters:
aPtr A pointer to the concrete object.
aTypeName The class name of the type
aInstanceSize The size of the type
void NS_LogDtor ( void *  aPtr,
const char *  aTypeName,
PRUint32  aInstanceSize 
)
void NS_LogInit (  ) 

Perform a stack-walk to a debugging log under various circumstances.

Used to aid debugging of leaked object graphs.

The NS_Log* functions are available in both debug and release builds of XPCOM, but the output will be useless unless binary debugging symbols for all modules in the stacktrace are available. By default, refcount logging is enabled at NS_InitXPCOM and refcount statistics are printed at NS_ShutdownXPCOM. NS_LogInit and NS_LogTerm allow applications to enable logging earlier and delay printing of logging statistics. They should always be used as a matched pair.

void NS_LogRelease ( void *  aPtr,
nsrefcnt  aNewRefCnt,
const char *  aTypeName 
)
void NS_LogTerm (  ) 
void* NS_Realloc ( void *  ptr,
PRSize  size 
)

Reallocates a block of memory to a new size.

Status:
FROZEN
Parameters:
ptr The block of memory to reallocate. This block must originally have been allocated by NS_Alloc or NS_Realloc
size The new size. If 0, frees the block like NS_Free
Returns:
The reallocated block of memory
Note:
This function is thread-safe.

If ptr is null, this function behaves like NS_Alloc. If s is the size of the block to which ptr points, the first min(s, size) bytes of ptr's block are copied to the new block. If the allocation succeeds, ptr is freed and a pointer to the new block is returned. If the allocation fails, ptr is not freed and null is returned. The returned value may be the same as ptr.

nsresult NS_ShutdownXPCOM ( nsIServiceManager servMgr  ) 

Shutdown XPCOM.

You must call this method after you are finished using xpcom.

Status:
FROZEN
Parameters:
servMgr The service manager which was returned by NS_InitXPCOM. This will release servMgr. You may pass null.
Returns:
NS_OK for success; other error codes indicate a failure during initialisation.