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:

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
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_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)
nsPurpleBufferEntry *	NS_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.

#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.

#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.

#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.

#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.

#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

#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.

---

Typedef Documentation

typedef struct nsACString nsACString

typedef struct nsAString nsAString

typedef struct nsIComponentManager nsIComponentManager

typedef struct nsIComponentRegistrar nsIComponentRegistrar

typedef struct nsIDebug nsIDebug

typedef struct nsIDirectoryServiceProvider nsIDirectoryServiceProvider

typedef struct nsIFile nsIFile

typedef struct nsILocalFile nsILocalFile

typedef struct nsIMemory nsIMemory

typedef struct nsIModule nsIModule

typedef struct nsIServiceManager nsIServiceManager

typedef struct nsISupports nsISupports

typedef struct nsITraceRefcnt nsITraceRefcnt

typedef struct nsPurpleBufferEntry nsPurpleBufferEntry

---

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.