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/. */
11 #include "nsXPCOMCID.h"
12 #include "mozilla/Attributes.h"
13 #include "mozilla/Atomics.h"
16 # define DECL_CLASS(c) class c
17 # define DECL_STRUCT(c) struct c
19 # define DECL_CLASS(c) typedef struct c c
20 # define DECL_STRUCT(c) typedef struct c c
23 DECL_CLASS(nsISupports
);
24 DECL_CLASS(nsIComponentManager
);
25 DECL_CLASS(nsIComponentRegistrar
);
26 DECL_CLASS(nsIServiceManager
);
28 DECL_CLASS(nsIDirectoryServiceProvider
);
29 DECL_CLASS(nsIMemory
);
30 DECL_CLASS(nsIDebug2
);
33 extern bool gXPCOMShuttingDown
;
34 extern bool gXPCOMMainThreadEventsAreDoomed
;
38 # include "nsStringFwd.h"
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.
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.
51 * @param aResult The service manager. You may pass null.
53 * @param aBinDirectory The directory containing the component
54 * registry and runtime libraries;
55 * or use <CODE>nullptr</CODE> to use the working
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.
63 * @param aInitJSContext Whether the nsXPCJSContext should be initialized at
66 * @see NS_NewLocalFile
68 * @see nsIDirectoryServiceProvider
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
77 NS_InitXPCOM(nsIServiceManager
** aResult
, nsIFile
* aBinDirectory
,
78 nsIDirectoryServiceProvider
* aAppFileLocationProvider
,
79 bool aInitJSContext
= true);
82 * Initialize only minimal components of XPCOM. This ensures nsThreadManager,
83 * logging, and timers will work.
86 NS_InitMinimalXPCOM();
89 * Shutdown XPCOM. You must call this method after you are finished
92 * @param aServMgr The service manager which was returned by
93 * NS_InitXPCOM. This will release servMgr. You may pass null.
95 * @return NS_OK for success;
96 * other error codes indicate a failure during initialisation.
98 * MOZ_CAN_RUN_SCRIPT_BOUNDARY for now, but really it should maybe be
101 XPCOM_API(MOZ_CAN_RUN_SCRIPT_BOUNDARY nsresult
)
102 NS_ShutdownXPCOM(nsIServiceManager
* aServMgr
);
105 * Public Method to access to the service manager.
107 * @param aResult Interface pointer to the service manager
109 * @return NS_OK for success;
110 * other error codes indicate a failure during initialisation.
112 XPCOM_API(nsresult
) NS_GetServiceManager(nsIServiceManager
** aResult
);
115 * Public Method to access to the component manager.
117 * @param aResult Interface pointer to the service
119 * @return NS_OK for success;
120 * other error codes indicate a failure during initialisation.
122 XPCOM_API(nsresult
) NS_GetComponentManager(nsIComponentManager
** aResult
);
125 * Public Method to access to the component registration manager.
127 * @param aResult Interface pointer to the service
129 * @return NS_OK for success;
130 * other error codes indicate a failure during initialisation.
132 XPCOM_API(nsresult
) NS_GetComponentRegistrar(nsIComponentRegistrar
** aResult
);
135 * Public Method to create an instance of a nsIFile. This function
136 * may be called prior to NS_InitXPCOM.
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
149 * @param aResult Interface pointer to a new instance of an nsIFile
151 * @return NS_OK for success;
152 * other error codes indicate a failure.
158 NS_NewLocalFile(const nsAString
& aPath
, bool aFollowLinks
, nsIFile
** aResult
);
161 NS_NewNativeLocalFile(const nsACString
& aPath
, bool aFollowLinks
,
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;
174 * Support for warnings, assertions, and debugging breaks.
178 NS_DEBUG_WARNING
= 0,
179 NS_DEBUG_ASSERTION
= 1,
185 * Print a runtime assertion. This function is available in both debug and
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
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)
200 NS_DebugBreak(uint32_t aSeverity
, const char* aStr
, const char* aExpr
,
201 const char* aFile
, int32_t aLine
);
204 * Perform a stack-walk to a debugging log under various
205 * circumstances. Used to aid debugging of leaked object graphs.
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.
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
219 XPCOM_API(void) NS_LogInit();
221 XPCOM_API(void) NS_LogTerm();
225 * A helper class that calls NS_LogInit in its constructor and
226 * NS_LogTerm in its destructor.
229 class ScopedLogging
{
231 ScopedLogging() { NS_LogInit(); }
233 ~ScopedLogging() { NS_LogTerm(); }
238 * Log construction and destruction of objects. Processing tools can use the
239 * stacktraces printed by these functions to identify objects that are being
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
248 NS_LogCtor(void* aPtr
, const char* aTypeName
, uint32_t aInstanceSize
);
251 NS_LogDtor(void* aPtr
, const char* aTypeName
, uint32_t aInstanceSize
);
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.
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
264 NS_LogAddRef(void* aPtr
, nsrefcnt aNewRefCnt
, const char* aTypeName
,
265 uint32_t aInstanceSize
);
268 NS_LogRelease(void* aPtr
, nsrefcnt aNewRefCnt
, const char* aTypeName
);
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.
276 * @param aCOMPtr the address of the COMPtr holding a strong reference
277 * @param aObject the object being referenced by the COMPtr
280 XPCOM_API(void) NS_LogCOMPtrAddRef(void* aCOMPtr
, nsISupports
* aObject
);
282 XPCOM_API(void) NS_LogCOMPtrRelease(void* aCOMPtr
, nsISupports
* aObject
);
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.
292 class nsCycleCollectionParticipant
;
293 class nsCycleCollectingAutoRefCnt
;
296 NS_CycleCollectorSuspect3(void* aPtr
, nsCycleCollectionParticipant
* aCp
,
297 nsCycleCollectingAutoRefCnt
* aRefCnt
,
298 bool* aShouldDelete
);
303 * Categories (in the category manager service) used by XPCOM:
307 * A category which is read after component registration but before
308 * the "xpcom-startup" notifications. Each category entry is treated
309 * as the contract ID of a service which implements
310 * nsIDirectoryServiceProvider. Each directory service provider is
311 * installed in the global directory service.
313 #define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
316 * A category which is read after component registration but before
317 * NS_InitXPCOM returns. Each category entry is treated as the contractID of
318 * a service: each service is instantiated, and if it implements nsIObserver
319 * the nsIObserver.observe method is called with the "xpcom-startup" topic.
321 #define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
324 * Observer topics (in the observer service) used by XPCOM:
328 * At XPCOM startup after component registration is complete, the
329 * following topic is notified. In order to receive this notification,
330 * component must register their contract ID in the category manager,
332 * @see NS_XPCOM_STARTUP_CATEGORY
334 #define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
337 * At XPCOM shutdown, this topic is notified just before "xpcom-shutdown".
338 * Components should only use this to mark themselves as 'being destroyed'.
339 * Nothing should be dispatched to any event loop.
341 #define NS_XPCOM_WILL_SHUTDOWN_OBSERVER_ID "xpcom-will-shutdown"
344 * At XPCOM shutdown, this topic is notified. All components must
345 * release any interface references to objects in other modules when
346 * this topic is notified.
348 #define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
351 * This topic is notified when an entry was added to a category in the
352 * category manager. The subject of the notification will be the name of
353 * the added entry as an nsISupportsCString, and the data will be the
354 * name of the category. The notification will occur on the main thread.
356 #define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID "xpcom-category-entry-added"
359 * This topic is notified when an entry was removed from a category in the
360 * category manager. The subject of the notification will be the name of
361 * the removed entry as an nsISupportsCString, and the data will be the
362 * name of the category. The notification will occur on the main thread.
364 #define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID \
365 "xpcom-category-entry-removed"
368 * This topic is notified when an a category was cleared in the category
369 * manager. The subject of the notification will be the category manager,
370 * and the data will be the name of the cleared category.
371 * The notification will occur on the main thread.
373 #define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
375 XPCOM_API(nsresult
) NS_GetDebug(nsIDebug2
** aResult
);