Defines | Typedefs

nscore.h File Reference

#include "xpcom-config.h"
#include "prtypes.h"
#include "nsError.h"
Include dependency graph for nscore.h:

Defines

#define NS_VISIBILITY_HIDDEN
 Make sure that we have the proper platform specific c++ definitions needed by nscore.h.
#define NS_VISIBILITY_DEFAULT
#define NS_HIDDEN_(type)   NS_VISIBILITY_HIDDEN type
#define NS_EXTERNAL_VIS_(type)   NS_VISIBILITY_DEFAULT type
#define NS_HIDDEN   NS_VISIBILITY_HIDDEN
#define NS_EXTERNAL_VIS   NS_VISIBILITY_DEFAULT
#define IMETHOD_VISIBILITY   NS_VISIBILITY_HIDDEN
#define NS_FASTCALL
 Mark a function as using a potentially non-standard function calling convention.
#define NS_CONSTRUCTOR_FASTCALL
#define NS_DEFCALL
#define NS_IMPORT   NS_EXTERNAL_VIS
#define NS_IMPORT_(type)   NS_EXTERNAL_VIS_(type)
#define NS_EXPORT   NS_EXTERNAL_VIS
#define NS_EXPORT_(type)   NS_EXTERNAL_VIS_(type)
#define NS_IMETHOD_(type)   virtual IMETHOD_VISIBILITY type NS_DEFCALL
#define NS_IMETHODIMP_(type)   type
#define NS_METHOD_(type)   type
#define NS_CALLBACK_(_type, _name)   _type (* _name)
#define NS_STDCALL
#define NS_FROZENCALL
#define NS_EXPORT_STATIC_MEMBER_(type)   NS_EXTERNAL_VIS_(type)
#define NS_IMPORT_STATIC_MEMBER_(type)   NS_EXTERNAL_VIS_(type)
#define NS_STDCALL_FUNCPROTO(ret, name, class, func, args)   ret (NS_STDCALL class::*name) args
 Macro for creating typedefs for pointer-to-member types which are declared with stdcall.
#define NS_DEPRECATED
 Deprecated declarations.
#define NS_IMETHOD   NS_IMETHOD_(nsresult)
 Generic API modifiers which return the standard XPCOM nsresult type.
#define NS_IMETHODIMP   NS_IMETHODIMP_(nsresult)
#define NS_METHOD   NS_METHOD_(nsresult)
#define NS_CALLBACK(_name)   NS_CALLBACK_(nsresult, _name)
#define NS_EXTERN_C
 Import/Export macros for XPCOM APIs.
#define EXPORT_XPCOM_API(type)   NS_EXTERN_C NS_EXPORT type NS_FROZENCALL
#define IMPORT_XPCOM_API(type)   NS_EXTERN_C NS_IMPORT type NS_FROZENCALL
#define GLUE_XPCOM_API(type)   NS_EXTERN_C NS_HIDDEN_(type) NS_FROZENCALL
#define XPCOM_API(type)   IMPORT_XPCOM_API(type)
#define NS_COM   NS_IMPORT
#define NS_COM_GLUE
#define NS_NO_VTABLE
 NS_NO_VTABLE is emitted by xpidl in interface declarations whenever xpidl can determine that the interface can't contain a constructor.
#define nsnull   0
 The preferred symbol for null.
#define NS_SPECIALIZE_TEMPLATE   template <>
#define NS_PTR_TO_INT32(x)   ((PRInt32) (PRWord) (x))
#define NS_PTR_TO_UINT32(x)   ((PRUint32) (PRWord) (x))
#define NS_INT32_TO_PTR(x)   ((void *) (PRWord) (x))
#define NS_STRINGIFY_HELPER(x_)   #x_
#define NS_STRINGIFY(x_)   NS_STRINGIFY_HELPER(x_)
#define NS_LIKELY(x)   (!!(x))
#define NS_UNLIKELY(x)   (!!(x))
#define NS_STACK_CLASS
 Static type annotations, enforced when static-checking is enabled:
#define NS_OKONHEAP
#define NS_SUPPRESS_STACK_CHECK
#define NS_FINAL_CLASS
#define NS_MUST_OVERRIDE
#define NS_SCRIPTABLE
 Attributes defined to help Dehydra GCC analysis.
#define NS_INPARAM
#define NS_OUTPARAM
#define NS_INOUTPARAM
#define NS_OVERRIDE

Typedefs

typedef PRUint32 nsresult
 Generic XPCOM result data type.
typedef PRUint32 nsrefcnt
 Reference count values.

Define Documentation

#define EXPORT_XPCOM_API (   type  )     NS_EXTERN_C NS_EXPORT type NS_FROZENCALL
#define GLUE_XPCOM_API (   type  )     NS_EXTERN_C NS_HIDDEN_(type) NS_FROZENCALL
#define IMETHOD_VISIBILITY   NS_VISIBILITY_HIDDEN
#define IMPORT_XPCOM_API (   type  )     NS_EXTERN_C NS_IMPORT type NS_FROZENCALL
#define NS_CALLBACK (   _name  )     NS_CALLBACK_(nsresult, _name)
#define NS_CALLBACK_ (   _type,
  _name 
)    _type (* _name)
#define NS_COM   NS_IMPORT
#define NS_COM_GLUE
#define NS_CONSTRUCTOR_FASTCALL
#define NS_DEFCALL
#define NS_DEPRECATED

Deprecated declarations.

#define NS_EXPORT   NS_EXTERNAL_VIS
#define NS_EXPORT_ (   type  )     NS_EXTERNAL_VIS_(type)
#define NS_EXPORT_STATIC_MEMBER_ (   type  )     NS_EXTERNAL_VIS_(type)
#define NS_EXTERN_C

Import/Export macros for XPCOM APIs.

#define NS_EXTERNAL_VIS   NS_VISIBILITY_DEFAULT
#define NS_EXTERNAL_VIS_ (   type  )     NS_VISIBILITY_DEFAULT type
#define NS_FASTCALL

Mark a function as using a potentially non-standard function calling convention.

This can be used on functions that are called very frequently, to reduce the overhead of the function call. It is still worth using the macro for C++ functions which take no parameters since it allows passing |this| in a register.

  • Do not use this on any scriptable interface method since xptcall won't be aware of the different calling convention.
  • This must appear on the declaration, not the definition.
  • Adding this to a public function _will_ break binary compatibility.
  • This may be used on virtual functions but you must ensure it is applied to all implementations - the compiler will _not_ warn but it will crash.
  • This has no effect for inline functions or functions which take a variable number of arguments.
  • __fastcall on windows should not be applied to class constructors/destructors - use the NS_CONSTRUCTOR_FASTCALL macro for constructors/destructors.

Examples: int NS_FASTCALL func1(char *foo); NS_HIDDEN_(int) NS_FASTCALL func2(char *foo);

#define NS_FINAL_CLASS
#define NS_FROZENCALL
#define NS_HIDDEN   NS_VISIBILITY_HIDDEN
#define NS_HIDDEN_ (   type  )     NS_VISIBILITY_HIDDEN type
#define NS_IMETHOD   NS_IMETHOD_(nsresult)

Generic API modifiers which return the standard XPCOM nsresult type.

#define NS_IMETHOD_ (   type  )     virtual IMETHOD_VISIBILITY type NS_DEFCALL
#define NS_IMETHODIMP   NS_IMETHODIMP_(nsresult)
#define NS_IMETHODIMP_ (   type  )     type
#define NS_IMPORT   NS_EXTERNAL_VIS
#define NS_IMPORT_ (   type  )     NS_EXTERNAL_VIS_(type)
#define NS_IMPORT_STATIC_MEMBER_ (   type  )     NS_EXTERNAL_VIS_(type)
#define NS_INOUTPARAM
#define NS_INPARAM
#define NS_INT32_TO_PTR (   x  )     ((void *) (PRWord) (x))
#define NS_LIKELY (   x  )     (!!(x))
#define NS_METHOD   NS_METHOD_(nsresult)
#define NS_METHOD_ (   type  )     type
#define NS_MUST_OVERRIDE
#define NS_NO_VTABLE

NS_NO_VTABLE is emitted by xpidl in interface declarations whenever xpidl can determine that the interface can't contain a constructor.

This results in some space savings and possible runtime savings - see bug 49416. We undefine it first, as xpidl-generated headers define it for IDL uses that don't include this file.

#define NS_OKONHEAP
#define NS_OUTPARAM
#define NS_OVERRIDE
#define NS_PTR_TO_INT32 (   x  )     ((PRInt32) (PRWord) (x))
#define NS_PTR_TO_UINT32 (   x  )     ((PRUint32) (PRWord) (x))
#define NS_SCRIPTABLE

Attributes defined to help Dehydra GCC analysis.

#define NS_SPECIALIZE_TEMPLATE   template <>
#define NS_STACK_CLASS

Static type annotations, enforced when static-checking is enabled:

NS_STACK_CLASS: a class which must only be instantiated on the stack NS_FINAL_CLASS: a class which may not be subclassed

NS_MUST_OVERRIDE: a method which every immediate subclass of this class must override. A subclass override can itself be NS_MUST_OVERRIDE, in which case its own subclasses must override the method as well.

This is similar to, but not the same as, marking a method pure virtual. It has no effect on the class in which the annotation appears, you can still provide a definition for the method, and it objects to the mere existence of a subclass that doesn't override the method. See examples in analysis/must-override.js.

#define NS_STDCALL
#define NS_STDCALL_FUNCPROTO (   ret,
  name,
  class,
  func,
  args 
)    ret (NS_STDCALL class::*name) args

Macro for creating typedefs for pointer-to-member types which are declared with stdcall.

It is important to use this for any type which is declared as stdcall (i.e. NS_IMETHOD). For example, instead of writing:

typedef nsresult (nsIFoo::*someType)(nsISupports* arg);

you should write:

typedef NS_STDCALL_FUNCPROTO(nsresult, someType, nsIFoo, typeFunc, (nsISupports*));

where nsIFoo::typeFunc is any method declared as NS_IMETHOD typeFunc(nsISupports*);

XXX this can be simplified to always use the non-typeof implementation when http://gcc.gnu.org/bugzilla/show_bug.cgi?id=11893 is fixed.

#define NS_STRINGIFY (   x_  )     NS_STRINGIFY_HELPER(x_)
#define NS_STRINGIFY_HELPER (   x_  )     #x_
#define NS_SUPPRESS_STACK_CHECK
#define NS_UNLIKELY (   x  )     (!!(x))
#define NS_VISIBILITY_DEFAULT
#define NS_VISIBILITY_HIDDEN

Make sure that we have the proper platform specific c++ definitions needed by nscore.h.

Incorporate the core NSPR data types which XPCOM uses. Macros defining the target platform... Using the visibility("hidden") attribute allows the compiler to use PC-relative addressing to call this function. If a function does not access any global data, and does not call any methods which are not either file-local or hidden, then on ELF systems we avoid loading the address of the PLT into a register at the start of the function, which reduces code size and frees up a register for general use.

As a general rule, this should be used for any non-exported symbol (including virtual method implementations). NS_IMETHOD uses this by default; if you need to have your NS_IMETHOD functions exported, you can wrap your class as follows:

undef IMETHOD_VISIBILITY define IMETHOD_VISIBILITY NS_VISIBILITY_DEFAULT

class Foo { ... };

undef IMETHOD_VISIBILITY define IMETHOD_VISIBILITY NS_VISIBILITY_HIDDEN

Don't forget to change the visibility back to hidden before the end of a header!

Other examples:

NS_HIDDEN_(int) someMethod(); SomeCtor() NS_HIDDEN;

SSARG_PRESCONTEXT SSARG_PRESCONTEXT nsnull   0

The preferred symbol for null.

#define XPCOM_API (   type  )     IMPORT_XPCOM_API(type)

Typedef Documentation

typedef PRUint32 nsrefcnt

Reference count values.

This is the return type for AddRef() and Release() in nsISupports. IUnknown of COM returns an unsigned long from equivalent functions. The following ifdef exists to maintain binary compatibility with IUnknown.

typedef PRUint32 nsresult

Generic XPCOM result data type.