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