The Tor Browser / file comparison

comparison: xpcom/build/nsXPCOM.h

xpcom/build/nsXPCOM.h

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial