PageRenderTime 24ms CodeModel.GetById 14ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/gecko_api/include/nsXPCOM.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 556 lines | 137 code | 53 blank | 366 comment | 0 complexity | a87eddad666cbbcdbc55e248f024ae74 MD5 | raw file
  1/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is mozilla.org code.
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1998
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *   Benjamin Smedberg <benjamin@smedbergs.us>
 24 *
 25 * Alternatively, the contents of this file may be used under the terms of
 26 * either of the GNU General Public License Version 2 or later (the "GPL"),
 27 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 28 * in which case the provisions of the GPL or the LGPL are applicable instead
 29 * of those above. If you wish to allow use of your version of this file only
 30 * under the terms of either the GPL or the LGPL, and not to allow others to
 31 * use your version of this file under the terms of the MPL, indicate your
 32 * decision by deleting the provisions above and replace them with the notice
 33 * and other provisions required by the GPL or the LGPL. If you do not delete
 34 * the provisions above, a recipient may use your version of this file under
 35 * the terms of any one of the MPL, the GPL or the LGPL.
 36 *
 37 * ***** END LICENSE BLOCK ***** */
 38
 39#ifndef nsXPCOM_h__
 40#define nsXPCOM_h__
 41
 42/* Map frozen functions to private symbol names if not using strict API. */
 43#ifdef MOZILLA_INTERNAL_API
 44# define NS_InitXPCOM2               NS_InitXPCOM2_P
 45# define NS_InitXPCOM3               NS_InitXPCOM3_P
 46# define NS_ShutdownXPCOM            NS_ShutdownXPCOM_P
 47# define NS_GetServiceManager        NS_GetServiceManager_P
 48# define NS_GetComponentManager      NS_GetComponentManager_P
 49# define NS_GetComponentRegistrar    NS_GetComponentRegistrar_P
 50# define NS_GetMemoryManager         NS_GetMemoryManager_P
 51# define NS_NewLocalFile             NS_NewLocalFile_P
 52# define NS_NewNativeLocalFile       NS_NewNativeLocalFile_P
 53# define NS_GetDebug                 NS_GetDebug_P
 54# define NS_GetTraceRefcnt           NS_GetTraceRefcnt_P
 55# define NS_Alloc                    NS_Alloc_P
 56# define NS_Realloc                  NS_Realloc_P
 57# define NS_Free                     NS_Free_P
 58# define NS_DebugBreak               NS_DebugBreak_P
 59# define NS_LogInit                  NS_LogInit_P
 60# define NS_LogTerm                  NS_LogTerm_P
 61# define NS_LogAddRef                NS_LogAddRef_P
 62# define NS_LogRelease               NS_LogRelease_P
 63# define NS_LogCtor                  NS_LogCtor_P
 64# define NS_LogDtor                  NS_LogDtor_P
 65# define NS_LogCOMPtrAddRef          NS_LogCOMPtrAddRef_P
 66# define NS_LogCOMPtrRelease         NS_LogCOMPtrRelease_P
 67# define NS_CycleCollectorSuspect    NS_CycleCollectorSuspect_P
 68# define NS_CycleCollectorForget     NS_CycleCollectorForget_P
 69#endif
 70
 71#include "nscore.h"
 72#include "nsXPCOMCID.h"
 73
 74#ifdef __cplusplus
 75#define DECL_CLASS(c) class c
 76#else
 77#define DECL_CLASS(c) typedef struct c c
 78#endif
 79
 80DECL_CLASS(nsAString);
 81DECL_CLASS(nsACString);
 82
 83DECL_CLASS(nsISupports);
 84DECL_CLASS(nsIModule);
 85DECL_CLASS(nsIComponentManager);
 86DECL_CLASS(nsIComponentRegistrar);
 87DECL_CLASS(nsIServiceManager);
 88DECL_CLASS(nsIFile);
 89DECL_CLASS(nsILocalFile);
 90DECL_CLASS(nsIDirectoryServiceProvider);
 91DECL_CLASS(nsIMemory);
 92DECL_CLASS(nsIDebug);
 93DECL_CLASS(nsITraceRefcnt);
 94
 95/**
 96 * Every XPCOM component implements this function signature, which is the
 97 * only entrypoint XPCOM uses to the function.
 98 *
 99 * @status FROZEN
100 */
101typedef nsresult (PR_CALLBACK *nsGetModuleProc)(nsIComponentManager *aCompMgr,
102                                                nsIFile* location,
103                                                nsIModule** return_cobj);
104
105/**
106 * Initialises XPCOM. You must call one of the NS_InitXPCOM methods
107 * before proceeding to use xpcom. The one exception is that you may
108 * call NS_NewLocalFile to create a nsIFile.
109 * 
110 * @status FROZEN
111 *
112 * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
113 *       to create the file object you supply as the bin directory path in this
114 *       call. The function may be safely called before the rest of XPCOM or 
115 *       embedding has been initialised.
116 *
117 * @param result           The service manager.  You may pass null.
118 *
119 * @param binDirectory     The directory containing the component
120 *                         registry and runtime libraries;
121 *                         or use <CODE>nsnull</CODE> to use the working
122 *                         directory.
123 *
124 * @param appFileLocationProvider The object to be used by Gecko that specifies
125 *                         to Gecko where to find profiles, the component
126 *                         registry preferences and so on; or use
127 *                         <CODE>nsnull</CODE> for the default behaviour.
128 *
129 * @see NS_NewLocalFile
130 * @see nsILocalFile
131 * @see nsIDirectoryServiceProvider
132 *
133 * @return NS_OK for success;
134 *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
135 *         which can happen if XPCOM is reloaded, but did not completly
136 *         shutdown. Other error codes indicate a failure during
137 *         initialisation.
138 */
139XPCOM_API(nsresult)
140NS_InitXPCOM2(nsIServiceManager* *result, 
141              nsIFile* binDirectory,
142              nsIDirectoryServiceProvider* appFileLocationProvider);
143
144/**
145 * Some clients of XPCOM have statically linked components (not dynamically
146 * loaded component DLLs), which can be passed to NS_InitXPCOM3 using this
147 * structure.
148 *
149 * @status FROZEN
150 */
151typedef struct nsStaticModuleInfo {
152  const char      *name;
153  nsGetModuleProc  getModule;
154} nsStaticModuleInfo;
155
156/**
157 * Initialises XPCOM with static components. You must call one of the
158 * NS_InitXPCOM methods before proceeding to use xpcom. The one
159 * exception is that you may call NS_NewLocalFile to create a nsIFile.
160 * 
161 * @status FROZEN
162 *
163 * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
164 *       to create the file object you supply as the bin directory path in this
165 *       call. The function may be safely called before the rest of XPCOM or 
166 *       embedding has been initialised.
167 *
168 * @param result           The service manager.  You may pass null.
169 *
170 * @param binDirectory     The directory containing the component
171 *                         registry and runtime libraries;
172 *                         or use <CODE>nsnull</CODE> to use the working
173 *                         directory.
174 *
175 * @param appFileLocationProvider The object to be used by Gecko that specifies
176 *                         to Gecko where to find profiles, the component
177 *                         registry preferences and so on; or use
178 *                         <CODE>nsnull</CODE> for the default behaviour.
179 *
180 * @param staticComponents An array of static components. Passing null causes
181 *                         default (builtin) components to be registered, if
182 *                         present.
183 * @param componentCount   Number of elements in staticComponents
184 *
185 * @see NS_NewLocalFile
186 * @see nsILocalFile
187 * @see nsIDirectoryServiceProvider
188 * @see XRE_GetStaticComponents
189 *
190 * @return NS_OK for success;
191 *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
192 *         which can happen if XPCOM is reloaded, but did not completly
193 *         shutdown. Other error codes indicate a failure during
194 *         initialisation.
195 */
196XPCOM_API(nsresult)
197NS_InitXPCOM3(nsIServiceManager* *result, 
198              nsIFile* binDirectory,
199              nsIDirectoryServiceProvider* appFileLocationProvider,
200              nsStaticModuleInfo const *staticComponents,
201              PRUint32 componentCount);
202
203/**
204 * Shutdown XPCOM. You must call this method after you are finished
205 * using xpcom. 
206 *
207 * @status FROZEN
208 *
209 * @param servMgr           The service manager which was returned by NS_InitXPCOM.
210 *                          This will release servMgr.  You may pass null.
211 *
212 * @return NS_OK for success;
213 *         other error codes indicate a failure during initialisation.
214 *
215 */
216XPCOM_API(nsresult)
217NS_ShutdownXPCOM(nsIServiceManager* servMgr);
218
219
220/**
221 * Public Method to access to the service manager.
222 * 
223 * @status FROZEN
224 * @param result Interface pointer to the service manager 
225 *
226 * @return NS_OK for success;
227 *         other error codes indicate a failure during initialisation.
228 *
229 */
230XPCOM_API(nsresult)
231NS_GetServiceManager(nsIServiceManager* *result);
232
233/**
234 * Public Method to access to the component manager.
235 * 
236 * @status FROZEN
237 * @param result Interface pointer to the service 
238 *
239 * @return NS_OK for success;
240 *         other error codes indicate a failure during initialisation.
241 *
242 */
243XPCOM_API(nsresult)
244NS_GetComponentManager(nsIComponentManager* *result);
245
246/**
247 * Public Method to access to the component registration manager.
248 * 
249 * @status FROZEN
250 * @param result Interface pointer to the service 
251 *
252 * @return NS_OK for success;
253 *         other error codes indicate a failure during initialisation.
254 *
255 */
256XPCOM_API(nsresult)
257NS_GetComponentRegistrar(nsIComponentRegistrar* *result);
258
259/**
260 * Public Method to access to the memory manager.  See nsIMemory
261 * 
262 * @status FROZEN
263 * @param result Interface pointer to the memory manager 
264 *
265 * @return NS_OK for success;
266 *         other error codes indicate a failure during initialisation.
267 *
268 */
269XPCOM_API(nsresult)
270NS_GetMemoryManager(nsIMemory* *result);
271
272/**
273 * Public Method to create an instance of a nsILocalFile.  This function
274 * may be called prior to NS_InitXPCOM.
275 * 
276 * @status FROZEN
277 * 
278 *   @param path       
279 *       A string which specifies a full file path to a 
280 *       location.  Relative paths will be treated as an
281 *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).       
282 *       |NS_NewNativeLocalFile|'s path must be in the 
283 *       filesystem charset.
284 *   @param followLinks
285 *       This attribute will determine if the nsLocalFile will auto
286 *       resolve symbolic links.  By default, this value will be false
287 *       on all non unix systems.  On unix, this attribute is effectively
288 *       a noop.  
289 * @param result Interface pointer to a new instance of an nsILocalFile 
290 *
291 * @return NS_OK for success;
292 *         other error codes indicate a failure.
293 */
294
295#ifdef __cplusplus
296
297XPCOM_API(nsresult)
298NS_NewLocalFile(const nsAString &path, 
299                PRBool followLinks, 
300                nsILocalFile* *result);
301
302XPCOM_API(nsresult)
303NS_NewNativeLocalFile(const nsACString &path, 
304                      PRBool followLinks, 
305                      nsILocalFile* *result);
306
307#endif
308
309/**
310 * Allocates a block of memory of a particular size. If the memory cannot
311 * be allocated (because of an out-of-memory condition), null is returned.
312 *
313 * @status FROZEN
314 *
315 * @param size   The size of the block to allocate
316 * @result       The block of memory
317 * @note         This function is thread-safe.
318 */
319XPCOM_API(void*)
320NS_Alloc(PRSize size);
321
322/**
323 * Reallocates a block of memory to a new size.
324 *
325 * @status FROZEN
326 *
327 * @param ptr     The block of memory to reallocate. This block must originally
328                  have been allocated by NS_Alloc or NS_Realloc
329 * @param size    The new size. If 0, frees the block like NS_Free
330 * @result        The reallocated block of memory
331 * @note          This function is thread-safe.
332 *
333 * If ptr is null, this function behaves like NS_Alloc.
334 * If s is the size of the block to which ptr points, the first min(s, size)
335 * bytes of ptr's block are copied to the new block. If the allocation
336 * succeeds, ptr is freed and a pointer to the new block is returned. If the
337 * allocation fails, ptr is not freed and null is returned. The returned
338 * value may be the same as ptr.
339 */
340XPCOM_API(void*)
341NS_Realloc(void* ptr, PRSize size);
342
343/**
344 * Frees a block of memory. Null is a permissible value, in which case no
345 * action is taken.
346 *
347 * @status FROZEN
348 *
349 * @param ptr   The block of memory to free. This block must originally have
350 *              been allocated by NS_Alloc or NS_Realloc
351 * @note        This function is thread-safe.
352 */
353XPCOM_API(void)
354NS_Free(void* ptr);
355
356/**
357 * Support for warnings, assertions, and debugging breaks.
358 */
359
360enum {
361    NS_DEBUG_WARNING = 0,
362    NS_DEBUG_ASSERTION = 1,
363    NS_DEBUG_BREAK = 2,
364    NS_DEBUG_ABORT = 3
365};
366
367/**
368 * Print a runtime assertion. This function is available in both debug and
369 * release builds.
370 * 
371 * @note Based on the value of aSeverity and the XPCOM_DEBUG_BREAK
372 * environment variable, this function may cause the application to
373 * print the warning, print a stacktrace, break into a debugger, or abort
374 * immediately.
375 *
376 * @param aSeverity A NS_DEBUG_* value
377 * @param aStr   A readable error message (ASCII, may be null)
378 * @param aExpr  The expression evaluated (may be null)
379 * @param aFile  The source file containing the assertion (may be null)
380 * @param aLine  The source file line number (-1 indicates no line number)
381 */
382XPCOM_API(void)
383NS_DebugBreak(PRUint32 aSeverity,
384              const char *aStr, const char *aExpr,
385              const char *aFile, PRInt32 aLine);
386
387/**
388 * Perform a stack-walk to a debugging log under various
389 * circumstances. Used to aid debugging of leaked object graphs.
390 *
391 * The NS_Log* functions are available in both debug and release
392 * builds of XPCOM, but the output will be useless unless binary
393 * debugging symbols for all modules in the stacktrace are available.
394 */
395
396/**
397 * By default, refcount logging is enabled at NS_InitXPCOM and
398 * refcount statistics are printed at NS_ShutdownXPCOM. NS_LogInit and
399 * NS_LogTerm allow applications to enable logging earlier and delay
400 * printing of logging statistics. They should always be used as a
401 * matched pair.
402 */
403XPCOM_API(void)
404NS_LogInit();
405
406XPCOM_API(void)
407NS_LogTerm();
408
409/**
410 * Log construction and destruction of objects. Processing tools can use the
411 * stacktraces printed by these functions to identify objects that are being
412 * leaked.
413 *
414 * @param aPtr          A pointer to the concrete object.
415 * @param aTypeName     The class name of the type
416 * @param aInstanceSize The size of the type
417 */
418
419XPCOM_API(void)
420NS_LogCtor(void *aPtr, const char *aTypeName, PRUint32 aInstanceSize);
421
422XPCOM_API(void)
423NS_LogDtor(void *aPtr, const char *aTypeName, PRUint32 aInstanceSize);
424
425/**
426 * Log a stacktrace when an XPCOM object's refcount is incremented or
427 * decremented. Processing tools can use the stacktraces printed by these
428 * functions to identify objects that were leaked due to XPCOM references.
429 *
430 * @param aPtr          A pointer to the concrete object
431 * @param aNewRefCnt    The new reference count.
432 * @param aTypeName     The class name of the type
433 * @param aInstanceSize The size of the type
434 */
435XPCOM_API(void)
436NS_LogAddRef(void *aPtr, nsrefcnt aNewRefCnt,
437             const char *aTypeName, PRUint32 aInstanceSize);
438
439XPCOM_API(void)
440NS_LogRelease(void *aPtr, nsrefcnt aNewRefCnt, const char *aTypeName);
441
442/**
443 * Log reference counting performed by COMPtrs. Processing tools can
444 * use the stacktraces printed by these functions to simplify reports
445 * about leaked objects generated from the data printed by
446 * NS_LogAddRef/NS_LogRelease.
447 *
448 * @param aCOMPtr the address of the COMPtr holding a strong reference
449 * @param aObject the object being referenced by the COMPtr
450 */
451
452XPCOM_API(void)
453NS_LogCOMPtrAddRef(void *aCOMPtr, nsISupports *aObject);
454
455XPCOM_API(void)
456NS_LogCOMPtrRelease(void *aCOMPtr, nsISupports *aObject);
457
458/**
459 * The XPCOM cycle collector analyzes and breaks reference cycles between
460 * participating XPCOM objects. All objects in the cycle must implement
461 * nsCycleCollectionParticipant to break cycles correctly.
462 */
463XPCOM_API(PRBool)
464NS_CycleCollectorSuspect(nsISupports *n);
465
466XPCOM_API(PRBool)
467NS_CycleCollectorForget(nsISupports *n);
468
469/**
470 * Categories (in the category manager service) used by XPCOM:
471 */
472
473/**
474 * A category which is read after component registration but before
475 * the "xpcom-startup" notifications. Each category entry is treated
476 * as the contract ID of a service which implements
477 * nsIDirectoryServiceProvider. Each directory service provider is
478 * installed in the global directory service.
479 *
480 * @status FROZEN
481 */
482#define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
483
484/**
485 * A category which is read after component registration but before
486 * NS_InitXPCOM returns. Each category entry is treated as the contractID of
487 * a service: each service is instantiated, and if it implements nsIObserver
488 * the nsIObserver.observe method is called with the "xpcom-startup" topic.
489 *
490 * @status FROZEN
491 */
492#define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
493
494
495/**
496 * Observer topics (in the observer service) used by XPCOM:
497 */
498
499/**
500 * At XPCOM startup after component registration is complete, the
501 * following topic is notified. In order to receive this notification,
502 * component must register their contract ID in the category manager,
503 *
504 * @see NS_XPCOM_STARTUP_CATEGORY
505 * @status FROZEN
506 */
507#define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
508
509/**
510 * At XPCOM shutdown, this topic is notified. All components must
511 * release any interface references to objects in other modules when
512 * this topic is notified.
513 *
514 * @status FROZEN
515 */
516#define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
517
518/**
519 * This topic is notified when an entry was added to a category in the
520 * category manager. The subject of the notification will be the name of
521 * the added entry as an nsISupportsCString, and the data will be the
522 * name of the category. The notification will occur on the main thread.
523 *
524 * @status FROZEN
525 */
526#define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID \
527  "xpcom-category-entry-added"
528
529/**
530 * This topic is notified when an entry was removed from a category in the
531 * category manager. The subject of the notification will be the name of
532 * the removed entry as an nsISupportsCString, and the data will be the
533 * name of the category. The notification will occur on the main thread.
534 *
535 * @status FROZEN
536 */
537#define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID \
538  "xpcom-category-entry-removed"
539
540/**
541 * This topic is notified when an a category was cleared in the category
542 * manager. The subject of the notification will be the category manager,
543 * and the data will be the name of the cleared category.
544 * The notification will occur on the main thread.
545 *
546 * @status FROZEN
547 */
548#define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
549
550XPCOM_API(nsresult)
551NS_GetDebug(nsIDebug* *result);
552
553XPCOM_API(nsresult)
554NS_GetTraceRefcnt(nsITraceRefcnt* *result);
555
556#endif