williamr@2: /*
williamr@2: * Copyright (c) 1994-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of the License "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: * e32\include\e32def.h
williamr@2: * NOTE: THIS FILE SHOULD BE ACCEPTABLE TO A C COMPILER
williamr@2: * 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef __E32DEF_H__
williamr@2: #define __E32DEF_H__
williamr@2: 
williamr@2: /*
williamr@2:  * __LEAVE_EQUALS_THROW__ requires the compiler to support C++ exceptions
williamr@2:  */
williamr@2: #ifndef __SUPPORT_CPP_EXCEPTIONS__
williamr@2: #undef __LEAVE_EQUALS_THROW__
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: #if defined(__VC32__)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __NO_CLASS_CONSTS__
williamr@2: #if (_MSC_VER >= 1200)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __NORETURN__ __declspec(noreturn)
williamr@2: #else
williamr@2: #define __NORETURN__
williamr@2: #endif
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __NORETURN_TERMINATOR()
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define IMPORT_C __declspec(dllexport)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define EXPORT_C __declspec(dllexport)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@4: #define IMPORT_D __declspec(dllexport)
williamr@4: /**
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@4: #define EXPORT_D __declspec(dllexport)
williamr@4: /**
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@2: #define NONSHARABLE_CLASS(x) class x
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define NONSHARABLE_STRUCT(x) struct x
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __NO_THROW throw()
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __THROW(t) throw(t)
williamr@2: #pragma warning( disable : 4355 )	/* 'this' used in base member initializer list */
williamr@2: #pragma warning( disable : 4511 )	/* copy constructor could not be generated */
williamr@2: #pragma warning( disable : 4512 )	/* assignment operator could not be generated */
williamr@2: #pragma warning( disable : 4514 )	/* unreferenced inline function has been removed */
williamr@2: #pragma warning( disable : 4699 )	/* Note: Using precompiled header %s */
williamr@2: #pragma warning( disable : 4710 )	/* function not inlined */
williamr@2: #pragma warning( disable : 4121 )	/* alignment sensitive to packing */
williamr@2: #pragma warning( disable : 4273 )
williamr@2: #pragma warning( disable : 4097 )	/* typedef-name 'identifier1' used as synonym for class-name 'identifier2' */
williamr@2: #pragma warning( disable : 4291 )	/* 'TAny *CBase::operator new(TUint,TLeave)' : no matching operator delete found; memory will not be freed if initialization throws an exception */
williamr@2: 
williamr@2: #if _MSC_VER  >= 1100
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define TEMPLATE_SPECIALIZATION template<>
williamr@2: #else
williamr@2: #define TEMPLATE_SPECIALIZATION
williamr@2: #endif
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #if defined(__CW32__)
williamr@2: #undef __embedded_cplusplus
williamr@2: /** @internalTechnology */
williamr@2: #define __embedded_cplusplus	1
williamr@2: #define __NO_CLASS_CONSTS__
williamr@2: #define __NORETURN__
williamr@2: #define __NORETURN_TERMINATOR()
williamr@2: #define IMPORT_C __declspec(dllexport)
williamr@2: #define EXPORT_C __declspec(dllexport)
williamr@4: #define IMPORT_D __declspec(dllexport)
williamr@4: #define EXPORT_D __declspec(dllexport)
williamr@2: #define NONSHARABLE_CLASS(x) class x
williamr@2: #define NONSHARABLE_STRUCT(x) struct x
williamr@2: #define __NO_THROW throw()
williamr@2: #define __THROW(t) throw(t)
williamr@2: 
williamr@2: #define TEMPLATE_SPECIALIZATION template<>
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define _asm	asm
williamr@2: #ifndef __int64
williamr@2: #pragma longlong on
williamr@2: /** @internalTechnology */
williamr@2: #define __int64  long long
williamr@2: #endif
williamr@2: #ifndef __SUPPORT_CPP_EXCEPTIONS__
williamr@2: #pragma exceptions off    /* no support for C++ exception handling */
williamr@2: #pragma RTTI off          /* no support for C++ runtime type information */
williamr@2: #endif
williamr@2: #if __MWERKS__ >= 0x3200
williamr@2: #pragma warning off (10480)	/* deleteing void pointer is undefined */
williamr@2: #pragma warning off (10350) /* N pad byte(s) inserted after data member */
williamr@2: #endif
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@4: //
williamr@4: // GCC (ARM) compiler
williamr@4: //
williamr@4: #if defined(__GCC32__) && defined(__MARM__)
williamr@4: #ifndef __GNUC__		/* GCC98r2 doesn't define this for some reason */
williamr@4: #define __GNUC__	2
williamr@4: #endif
williamr@2: #define __NO_CLASS_CONSTS__
williamr@2: #define __NORETURN__  __attribute__ ((noreturn))
williamr@2: #ifdef __GCCV3__
williamr@2: #define __NORETURN_TERMINATOR()
williamr@2: #else
williamr@2: #define __NORETURN_TERMINATOR()		abort()
williamr@2: #endif
williamr@2: #define IMPORT_C
williamr@4: #define IMPORT_D
williamr@2: #if !defined __WINS__ && defined _WIN32 /* VC++ Browser Hack */
williamr@2: #define EXPORT_C
williamr@4: #define EXPORT_D
williamr@2: /** @internalTechnology */
williamr@2: #define asm(x)
williamr@2: #else
williamr@2: #define EXPORT_C __declspec(dllexport)
williamr@4: #define EXPORT_D __declspec(dllexport)
williamr@2: #endif
williamr@2: #define NONSHARABLE_CLASS(x) class x
williamr@2: #define NONSHARABLE_STRUCT(x) struct x
williamr@2: #define __NO_THROW
williamr@2: #define __THROW(t)
williamr@2: #ifdef __EABI__
williamr@2: #define TEMPLATE_SPECIALIZATION template<>
williamr@2: #else
williamr@2: #define TEMPLATE_SPECIALIZATION
williamr@2: #endif
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __DOUBLE_WORDS_SWAPPED__
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: /** @internalTechnology */
williamr@2: #define __NO_MUTABLE_KEYWORD
williamr@2: #if defined(__NO_MUTABLE_KEYWORD)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define __MUTABLE
williamr@2: #else
williamr@2: #define __MUTABLE mutable
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define CONST_CAST(type,exp) (const_cast<type>(exp))
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define STATIC_CAST(type,exp) (static_cast<type>(exp))
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define REINTERPRET_CAST(type,exp) (reinterpret_cast<type>(exp))
williamr@2: 
williamr@2: #if defined(__NO_MUTABLE_KEYWORD)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define MUTABLE_CAST(type,exp) (const_cast<type>(exp))
williamr@2: #else
williamr@2: #define MUTABLE_CAST(type,exp) (exp)
williamr@2: #endif
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define GLREF_D extern
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define GLDEF_D
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define LOCAL_D static
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define GLREF_C extern
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define GLDEF_C
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define LOCAL_C static
williamr@2: /**
williamr@4: @internalAll
williamr@4: @prototype
williamr@4: */
williamr@4: #ifndef IMPORT_D
williamr@4: #define IMPORT_D IMPORT_C 
williamr@4: #endif
williamr@4: 
williamr@4: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define FOREVER for(;;)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Symbolic definition for a true value.
williamr@2: */
williamr@2: #define TRUE 1
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Symbolic definition for a false value.
williamr@2: */
williamr@2: #define FALSE 0
williamr@2: #ifndef NULL
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Symbolic definition for a NULL value.
williamr@2: */
williamr@2: #define NULL 0
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef VA_START
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: A macro used by Symbian OS code for handling a variable argument list
williamr@2: in a function call.
williamr@2: 
williamr@2: Sets a pointer to point to the first of the variable arguments.
williamr@2: 
williamr@2: Typical usage:
williamr@2: 
williamr@2: @code
williamr@2: Foo(CAbcdef aAbcdef,...)
williamr@2:    {
williamr@2:    VA_LIST list;
williamr@2:    VA_START(list, aAbcdef);
williamr@2:    // other code
williamr@2:    } 
williamr@2: @endcode
williamr@2: 
williamr@2: @param ap   A pointer used to hold the address of an argument in
williamr@2:             the variable argument list. After execution of the code generated 
williamr@2:             by this macro, the pointer points to the first argument in
williamr@2:             the variable argument list.
williamr@2:             This symbol is usually declared as a VA_LIST type. 
williamr@2: 
williamr@2: @param pn   The argument that immediately precedes the variable argument list.
williamr@2: 
williamr@2: @see VA_LIST
williamr@2: @see VA_ARG
williamr@2: */
williamr@2: #define VA_START(ap,pn) ((ap)[0]=(TInt8 *)&pn+((sizeof(pn)+sizeof(TInt)-1)&~(sizeof(TInt)-1)),(void)0)
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef VA_ARG
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: A macro used by Symbian OS code for handling a variable argument list
williamr@2: in a function call.
williamr@2: 
williamr@2: Increments a pointer to a variable argument list to point to the next argument
williamr@2: in the list. The current argument is assumed to be of a type defined by
williamr@2: the second parameter to this macro.
williamr@2: 
williamr@2: Typical usage:
williamr@2: 
williamr@2: @code
williamr@2: Foo(CAbcdef aAbcdef,...)
williamr@2:    {
williamr@2:    VA_LIST list;
williamr@2:    VA_START(list, aAbcdef);
williamr@2:    ...
williamr@2:    TInt x = VA_ARG(list,TInt);
williamr@2:    ...
williamr@2:    const TDesC *pS=VA_ARG(aList,const TDesC*);
williamr@2:    ... 
williamr@2:    etc
williamr@2:    } 
williamr@2: @endcode
williamr@2: 
williamr@2: @param ap   A pointer used to hold the address of an argument in
williamr@2:             the variable argument list. It is assumed to point to the current
williamr@2:             argument in the variable argument list. After execution of the code
williamr@2:             generated by this macro, the pointer points to the next argument in
williamr@2:             the list. This symbol is usually declared as a VA_LIST type. 
williamr@2: 
williamr@2: @param type The type of the current argument.
williamr@2:             This can be any valid type, for example, TInt, const TDesC*, etc.
williamr@2:             
williamr@2: @see VA_LIST
williamr@2: @see VA_START            
williamr@2: */
williamr@2: #define VA_ARG(ap,type) ((ap)[0]+=((sizeof(type)+sizeof(TInt)-1)&~(sizeof(TInt)-1)),(*(type *)((ap)[0]-((sizeof(type)+sizeof(TInt)-1)&~(sizeof(TInt)-1)))))
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef VA_END
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: A macro used by Symbian OS code for handling a variable argument list
williamr@2: in a function call.
williamr@2: 
williamr@2: Sets a pointer to zero.
williamr@2: 
williamr@2: @param ap   A pointer used to hold the address of an argument in
williamr@2:             the variable argument list. After execution of the code generated 
williamr@2:             by this macro, the pointer is reset to 0.
williamr@2:             This symbol is usually declared as a VA_LIST type. 
williamr@2:             
williamr@2: @see VA_LIST
williamr@2: @see VA_START
williamr@2: @see VA_ARG            
williamr@2: */
williamr@2: #define VA_END(ap) ((ap)[0]=0,(void)0)
williamr@2: #endif
williamr@2: 	
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Calculates the offset of member f within class c.
williamr@2: 
williamr@2: This is used in the TSglQue and TDblQue constructors to set the offset of
williamr@2: the link object from the start of a list element.
williamr@2: 
williamr@2: @param c The name of the class.
williamr@2: @param f The name of the member within the specified class.
williamr@2: 
williamr@2: @see TSglQue
williamr@2: @see TDblQue
williamr@2: */
williamr@2: #ifndef _FOFF
williamr@2: #if __GNUC__ < 4
williamr@2: #define _FOFF(c,f)			(((TInt)&(((c *)0x1000)->f))-0x1000)
williamr@2: #else
williamr@4: #define _FOFF(c,f)			(__builtin_offsetof(c,f))
williamr@2: #endif
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @internalTechnology
williamr@2: @released
williamr@2: */
williamr@2: #define _ALIGN_DOWN(x,a)	((x)&~((a)-1))
williamr@2: /**
williamr@2: @internalTechnology
williamr@2: @released
williamr@2: */
williamr@2: #define _ALIGN_UP(x,a)		_ALIGN_DOWN((x)+(a)-1, a)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Pointer to any type.
williamr@2: 
williamr@2: TAny* is equivalent to void* in standard C or C++. TAny* is used in preference 
williamr@2: to void* because it is more suggestive of the actual meaning,
williamr@2: e.g. TAny* foo();.
williamr@2: 
williamr@2: TAny is not used where it really means "nothing", as in the declaration of 
williamr@2: functions which do not return a value; void is used instead, e.g. void Foo();.
williamr@2: */
williamr@2: typedef void TAny;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 8-bit signed integer type, used in Symbian OS to mean an 8-bit
williamr@2: signed integer, independent of the implementation.
williamr@2: */
williamr@2: typedef signed char TInt8;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 8-bit unsigned integer type; used in Symbian OS to mean an 8-bit
williamr@2: unsigned integer, independent of the implementation.
williamr@2: */
williamr@2: typedef unsigned char TUint8;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 16-bit signed integer type, used in Symbian OS to mean a 16-bit
williamr@2: signed integer, independent of the implementation.
williamr@2: */
williamr@2: typedef short int TInt16;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 16-bit unsigned integer type. used in Symbian OS to mean a 16-bit
williamr@2: unsigned integer, independent of the implementation.
williamr@2: */
williamr@2: typedef unsigned short int TUint16;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 32-bit signed integer type, used in Symbian OS to mean a 32-bit
williamr@2: signed integer, independent of the implementation.
williamr@2: */
williamr@2: typedef long int TInt32;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@4: A signed integer type of the same size as a pointer.
williamr@4: */
williamr@4: typedef TInt32 T_IntPtr;
williamr@4: typedef TInt32 TIntPtr;
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4: @publishedAll
williamr@4: @released
williamr@4: 
williamr@2: 32-bit unsigned integer type; used in Symbian OS to mean a 32-bit
williamr@2: unsigned integer, independent of the implementation.
williamr@2: */
williamr@2: typedef unsigned long int TUint32;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@4: An unsigned integer type of the same size as a pointer.
williamr@4: */
williamr@4: typedef TUint32 T_UintPtr;
williamr@4: typedef TUint32 TUintPtr;
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4: @publishedAll
williamr@4: @released
williamr@4: 
williamr@2: Signed integer type of the natural machine word length.
williamr@2: 
williamr@2: This is as defined by the C++ implementation's int type. In all
williamr@2: implementations, this is guaranteed to be at least 32 bits.
williamr@2: 
williamr@2: A TInt should be used in preference to a sized integer (TInt32, TInt16) for 
williamr@2: all general use. Sized integers should only be used when packing is essential. 
williamr@2: C++'s type conversion rules imply that all sized integers smaller than the 
williamr@2: natural machine word are in any case broadened to the natural machine word 
williamr@2: size when passed as function parameters.
williamr@2: 
williamr@2: A TInt should be used in preference to an unsigned integer (TUint) for all 
williamr@2: general use. Unsigned integers should only be used for flags (which use Boolean 
williamr@2: operations but not arithmetic) and, in very rare cases, for numbers whose 
williamr@2: range exceeds that available from signed integers. Although it is natural 
williamr@2: to attempt to use unsigned integers for quantities which cannot by nature 
williamr@2: be negative, the C++ language does not provide the support necessary to enforce 
williamr@2: the "expected" behaviour in these circumstances, and experience has shown 
williamr@2: that it is better to use signed integers unless there is good reason not to.
williamr@2: 
williamr@2: @see TUint
williamr@2: @see TInt32
williamr@2: @see TInt16
williamr@2: */
williamr@2: typedef signed int TInt;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Unsigned integer type of the natural machine word length. 
williamr@2: 
williamr@2: This is guaranteed to be at least 32 bits in all implementations.
williamr@2: 
williamr@2: In almost all circumstances, a TInt should be used in preference to a TUint. 
williamr@2: The main exception is in flags bytes.
williamr@2: 
williamr@2: @see TInt
williamr@2: */
williamr@2: typedef unsigned int TUint;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 32-bit floating point number, providing IEEE754 single precision on all Symbian 
williamr@2: OS implementations.
williamr@2: 
williamr@2: TReal should normally be used in preference to TReal32.
williamr@2: 
williamr@2: Use of floating-point numbers should generally be avoided unless a natural 
williamr@2: part of the problem specification. Most Symbian OS implementations do not 
williamr@2: have a hardware floating point unit: as a result, their floating-point performance 
williamr@2: is hundreds of times slower than integer performance.
williamr@2: */
williamr@2: typedef float TReal32;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 64-bit floating point number, providing IEEE754 double precision on all Symbian 
williamr@2: OS implementations.
williamr@2: 
williamr@2: Use of floating-point numbers should generally be avoided unless a natural 
williamr@2: part of the problem specification. Most Symbian OS implementations do not 
williamr@2: have a hardware floating point unit: as a result, their floating-point performance 
williamr@2: is hundreds of times slower than integer performance.
williamr@2: 
williamr@2: This type is identical to TReal.
williamr@2: 
williamr@2: @see TReal
williamr@2: */
williamr@2: typedef double TReal64;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 64-bit floating point number; identical to TReal64.
williamr@2: 
williamr@2: Use of floating-point numbers should generally be avoided unless a natural 
williamr@2: part of the problem specification. Most Symbian OS implementations do not 
williamr@2: have a hardware floating point unit: as a result, their floating-point performance 
williamr@2: is hundreds of times slower than integer performance.
williamr@2: 
williamr@2: Most serious floating-point calculations require double-precision. All standard 
williamr@2: math functions (see Math class) take double-precision arguments. Single-precision 
williamr@2: should only be used where space and performance are at a premium, and when 
williamr@2: their limited precision is acceptable.
williamr@2: 
williamr@2: @see TReal64
williamr@2: @see Math
williamr@2: */
williamr@2: typedef double TReal;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 8-bit unsigned character.
williamr@2: 
williamr@2: Use instead of C++ built-in char type because it is guaranteed to be unsigned. 
williamr@2: Use instead of TInt8 where the application is really for text rather than 
williamr@2: 8-bit arithmetic or binary quantities.
williamr@2: 
williamr@2: For most purposes, you should use TText rather than TText8. TText is mapped 
williamr@2: onto either TText8 or TText16 depending on whether a non-Unicode or Unicode 
williamr@2: variant is being built. Use TText8 only when you are dealing explicitly with 
williamr@2: 8-bit text, regardless of build.
williamr@2: 
williamr@2: @see TText */
williamr@2: typedef unsigned char TText8;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: 16-bit unsigned character.
williamr@2: 
williamr@2: Use instead of C++ wchar_t type because it is guaranteed to be unsigned. Use 
williamr@2: instead of TInt16 where the application is really for text rather than 8-bit 
williamr@2: arithmetic or binary quantities.
williamr@2: 
williamr@2: For most purposes, you should use TText rather than TText16. TText is mapped 
williamr@2: onto either TText8 or TText16 depending on whether a non-Unicode or Unicode 
williamr@2: variant is being built. Use TText16 only when you are dealing explicitly with 
williamr@2: 16-bit text, regardless of build.
williamr@2: 
williamr@2: @see TText
williamr@2: */
williamr@2: typedef unsigned short int TText16;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Boolean type which takes the value either ETrue or EFalse.
williamr@2: 
williamr@2: Although only a single bit would theoretically be necessary to represent a 
williamr@2: Boolean, a machine word is used instead, so that these quantities can be easily 
williamr@2: passed. Also, TBool must map onto int because of C++'s interpretation of 
williamr@2: operands in conditional expressions.
williamr@2: */
williamr@2: typedef int TBool;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: 
williamr@2: Defines a linear (virtual) address type.
williamr@2: */
williamr@4: typedef T_UintPtr TLinAddr;
williamr@4: 
williamr@2: 
williamr@2: 
williamr@2: #if defined(__GCC32__)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines a 64-bit signed integer type.
williamr@2: */
williamr@2: typedef long long Int64;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines a 64-bit unsigned integer type.
williamr@2: */
williamr@2: typedef unsigned long long Uint64;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define	I64LIT(x)	x##LL
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define	UI64LIT(x)	x##ULL
williamr@2: 
williamr@2: #elif defined(__VC32__)
williamr@2: typedef __int64 Int64;
williamr@2: typedef unsigned __int64 Uint64;
williamr@2: #define	I64LIT(x)	(__int64)##x
williamr@2: #define	UI64LIT(x)	(unsigned __int64)##x
williamr@2: 
williamr@2: #elif defined(__CW32__)
williamr@2: #pragma longlong on
williamr@2: typedef long long Int64;
williamr@2: typedef unsigned long long Uint64;
williamr@2: #define	I64LIT(x)	x##LL
williamr@2: #define	UI64LIT(x)	x##ULL
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines a 64-bit signed integer type.
williamr@2: 
williamr@2: NOTE: For those migrating from versions of Symbian OS before 8.1b (i.e. 8.1a, 7.0s etc)
williamr@2: TInt64 is now defined as a built-in type instead of as a class type. This means
williamr@2: that the member functions of the old TInt64 class are no longer exported
williamr@2: from EUSER.LIB, and represents a compatibility break.
williamr@2: 
williamr@2: To ease migration of source code, a number of macros are provided. Similar
williamr@2: macros have also been defined in Symbian OS versions 7.0s and 8.1a, but
williamr@2: implemented in terms of the old TInt64 class. This is important for code that
williamr@2: is common to : one or both of these Symbian OS versions, and to 8.1b and
williamr@2: subsequent versions.
williamr@2: 
williamr@2: The following list shows the new macros and the functions that they replace.
williamr@2: It also shows some alternative techniques.
williamr@2: In this list: x, v and r are declared as TInt64, c is declared as TInt, High
williamr@2: and Low are declared as TUint.
williamr@2: 
williamr@2: @code
williamr@2: OLD USAGE						REPLACEMENT
williamr@2: 
williamr@2: TInt64(High,Low);				MAKE_TINT64(High,Low);
williamr@2: x.Set(High,Low);				MAKE_TINT64(High,Low);
williamr@2: x.Low();						I64LOW(x);
williamr@2: x.High();						I64HIGH(x); 
williamr@2: x.GetTInt();					I64INT(x); 
williamr@2: x.GetTReal();					I64REAL(x); 
williamr@2: x.Lsr(c);						I64LSR(x,c); 
williamr@2: x.Mul10();						x*=10; 
williamr@2: x.MulTop(a);					I64MULTOP(x,a); 
williamr@2: x.DivMod(v,r);					r=x%v; x/=v;
williamr@2: @endcode 
williamr@2: */
williamr@2: typedef	Int64	TInt64;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2:  
williamr@2: Defines a 64-bit unsigned integer type.
williamr@2: */
williamr@2: typedef	Uint64	TUint64;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define _MAKE_TINT64_ZX(x)	((TInt64)((TUint32)(x)))
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define _MAKE_TUINT64_ZX(x)	((TUint64)((TUint32)(x)))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define MAKE_TINT64(h,l)	( (_MAKE_TINT64_ZX(h)<<32) | _MAKE_TINT64_ZX(l) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define MAKE_TUINT64(h,l)	( (_MAKE_TUINT64_ZX(h)<<32) | _MAKE_TUINT64_ZX(l) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to access the high order 32 bits of a 64 bit number.
williamr@2: */
williamr@2: #define	I64HIGH(x)			( (TUint32)((x)>>32) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to access the low order 32 bits of a 64 bit number.
williamr@2: */
williamr@2: #define	I64LOW(x)			( (TUint32)(x) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to cast a 64 bit value as an signed integer.
williamr@2: */
williamr@2: #define	I64INT(x)			( (TInt)(x) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to cast a 64 bit value as a TReal type.
williamr@2: */
williamr@2: #define	I64REAL(x)			( (TReal)(x) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to logically shift a 64 bit integer right.
williamr@2: */
williamr@2: #define	I64LSR(x, shift)	( *reinterpret_cast<TUint64*>(&(x)) >>= (shift) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to multiply a 64 bit integer by 10.
williamr@2: */
williamr@2: #define	I64MUL10(x)			( (x) *= 10 )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to divide a 64 bit integer by another and find the remainder.
williamr@2: */
williamr@2: #define	I64DIVMOD(x, divisor, remainder)	( ((remainder) = (x) % (divisor), (x) /= (divisor)) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates code to cast a double to a 64 bit integer.
williamr@2: */
williamr@2: #define	I64DOUBLECAST(x)	( static_cast<TInt64>(x) )
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated Use _LIT8 instead.
williamr@2: 
williamr@2: 8-bit literal.
williamr@2: 
williamr@2: The macro defines an explicit 8-bit constant literal which is suitable
williamr@2: for non-Unicode literal text, regardless of the build.
williamr@2: 
williamr@2: @see _L
williamr@2: @see _LIT8
williamr@2: @see _LIT
williamr@2: */
williamr@2: #define _L8(a) (TPtrC8((const TText8 *)(a)))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines an explicit 8-bit string which is suitable when non-Unicode text
williamr@2: is required, regardless of the build.
williamr@2: 
williamr@2: This is used by the deprecated literal descriptor _L8.
williamr@2: */
williamr@2: #define _S8(a) ((const TText8 *)a)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Constructs a constant literal descriptor of type TLitC8<TInt> with
williamr@2: the specified name and text.
williamr@2: 
williamr@2: The 8-bit build variant is generated for both non-Unicode and Unicode builds.
williamr@2: 
williamr@2: @param name The name of the C++ variable to be generated.
williamr@2: @param s    The literal text enclosed within a pair of double quotes. 
williamr@2: 
williamr@2: @see _LIT
williamr@2: */
williamr@2: #define _LIT8(name,s) const static TLitC8<sizeof(s)> name={sizeof(s)-1,s}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated Use _LIT16 instead.
williamr@2: 
williamr@2: 16-bit literal.
williamr@2: 
williamr@2: The macro defines an explicit 16-bit constant literal which is suitable
williamr@2: for Unicode literal text, regardless of the build.
williamr@2: 
williamr@2: @see _L
williamr@2: @see _LIT16
williamr@2: @see _LIT
williamr@2: */
williamr@2: #define _L16(a) (TPtrC16((const TText16 *)L ## a))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines an explicit 16-bit string which is suitable when Unicode text
williamr@2: is required, regardless of the build.
williamr@2: 
williamr@2: This is used by the deprecated literal descriptor _L16.
williamr@2: */
williamr@2: #define _S16(a) ((const TText16 *)L ## a)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Constructs a constant literal descriptor of type TLitC16<TInt> with
williamr@2: the specified name and text.
williamr@2: 
williamr@2: The 16-bit build variant is generated for both non-Unicode and Unicode builds.
williamr@2: 
williamr@2: @param name The name of the C++ variable to be generated.
williamr@2: @param s    The literal text enclosed within a pair of double quotes. 
williamr@2: 
williamr@2: @see _LIT
williamr@2: */
williamr@2: #define _LIT16(name,s) const static TLitC16<sizeof(L##s)/2> name={sizeof(L##s)/2-1,L##s}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #if defined(_UNICODE) && !defined(__KERNEL_MODE__)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Build independent general text character.
williamr@2: 
williamr@2: In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is 
williamr@2: mapped to TText16. Use the classes with explicit width only when you wish 
williamr@2: the width to be independent of the build variant.
williamr@2: 
williamr@2: Use this class rather than TChar for general use.
williamr@2: */
williamr@2: typedef TText16 TText;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated Use _LIT instead.
williamr@2: 
williamr@2: Build independent literal. 
williamr@2: 
williamr@2: The macro defines either an 8-bit constant literal (for non-Unicode text),
williamr@2: or a 16-bit constant literal (for Unicode text) depending on the build.
williamr@2: 
williamr@2: @see _LIT
williamr@2: @see _L16
williamr@2: @see _L8
williamr@2: */
williamr@2: #define _L(a) (TPtrC((const TText *)L ## a))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines either an 8-bit string (for non-Unicode text),
williamr@2: or a 16-bit string (for Unicode text) depending on the build.
williamr@2: 
williamr@2: This is used by the deprecated build independent literal _L.
williamr@2: */
williamr@2: #define _S(a) ((const TText *)L ## a)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Constructs a build independent constant literal descriptor of type TLitC<TInt>
williamr@2: with the specified name and text.
williamr@2: 
williamr@2: An 8-bit build variant is generated for a non-Unicode build;
williamr@2: A 16-bit build variant is generated for a Unicode build.
williamr@2: 
williamr@2: @param name The name of the C++ variable to be generated.
williamr@2: @param s    The literal text enclosed within a pair of double quotes. 
williamr@2: 
williamr@2: @see _LIT16
williamr@2: @see _LIT8
williamr@2: */
williamr@2: #define _LIT(name,s) const static TLitC<sizeof(L##s)/2> name={sizeof(L##s)/2-1,L##s}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #else
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Build independent general text character.
williamr@2: 
williamr@2: In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is 
williamr@2: mapped to TText16. Use the classes with explicit width only when you wish 
williamr@2: the width to be independent of the build variant.
williamr@2: 
williamr@2: Use this class rather than TChar for general use.
williamr@2: */
williamr@2: typedef TText8 TText;
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: @deprecated Use _LIT instead.
williamr@2: 
williamr@2: Build independent literal. 
williamr@2: 
williamr@2: The macro defines either an 8-bit constant literal (for non-Unicode text),
williamr@2: or a 16-bit constant literal (for Unicode text) depending on the build.
williamr@2: 
williamr@2: @see _LIT
williamr@2: @see _L16
williamr@2: @see _L8
williamr@2: */
williamr@2: #define _L(a) (TPtrC((const TText *)(a)))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines either an 8-bit string (for non-Unicode text),
williamr@2: or a 16-bit string (for Unicode text) depending on the build.
williamr@2: 
williamr@2: This is used by the deprecated build independent literal _L.
williamr@2: */
williamr@2: #define _S(a) ((const TText *)a)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Constructs a build independent constant literal descriptor of type TLitC<TInt>
williamr@2: with the specified name and text.
williamr@2: 
williamr@2: An 8-bit build variant is generated for a non-Unicode build;
williamr@2: A 16-bit build variant is generated for a Unicode build.
williamr@2: 
williamr@2: @param name The name of the C++ variable to be generated.
williamr@2: @param s    The literal text enclosed within a pair of double quotes. 
williamr@2: 
williamr@2: @see _LIT16
williamr@2: @see _LIT8
williamr@2: */
williamr@2: #define _LIT(name,s) const static TLitC<sizeof(s)> name={sizeof(s)-1,s}
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef __VA_LIST_defined
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Defines a 'C' style array of pointers to TInt8 types.
williamr@2: 
williamr@2: The type is most commonly used by code that needs to deal with a variable
williamr@2: number of arguments passed to a function.
williamr@2: 
williamr@2: @see TInt8
williamr@2: */
williamr@2: typedef TInt8 *VA_LIST[1];
williamr@2: #endif
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Asserts that a condition is true.
williamr@2: 
williamr@2: Code is generated for all builds.
williamr@2: 
williamr@2: This macro is used as a C++ statement to assert the truth of some condition,
williamr@2: and to take appropriate action if the condition is false. Unlike __ASSERT_DEBUG
williamr@2: it is defined in both release and debug builds.
williamr@2: 
williamr@2: The most common use for this macro is to check that the external environment of
williamr@2: a function or class is behaving as expected; for example, that parameters
williamr@2: passed to a function are credible, or that called functions are behaving as
williamr@2: expected; the macro is commonly placed at the beginning of a function.
williamr@2: 
williamr@2: The effect of the macro is to generate code which tests
williamr@2: the conditional expression c; if the expression is false, then
williamr@2: function p is called. In the majority of cases, the function p is one that
williamr@2: raises a panic.
williamr@2: 
williamr@2: Note that the macro definition is, in effect, equivalent to: 
williamr@2: 
williamr@2: @code
williamr@2: if !(c)p;
williamr@2: @endcode
williamr@2: 
williamr@2: @param c a conditional expression which results in true or false.
williamr@2: @param p a function which is called if the conditional expression c is false.
williamr@2: 
williamr@2: @see __ASSERT_DEBUG
williamr@2: */
williamr@2: #define __ASSERT_ALWAYS(c,p) (void)((c)||(p,0))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifdef __WINS__
williamr@2: #ifdef __CW32__
williamr@2: /** 
williamr@2: @internalAll
williamr@2: @released
williamr@2: */
williamr@2: #define __BREAKPOINT()			\
williamr@2: 	{							\
williamr@2: 	__asm { byte 0xcc };		\
williamr@2: 	}
williamr@2: #else // !__CW32__
williamr@2: /** 
williamr@2: @internalAll
williamr@2: @released
williamr@2: */
williamr@2: #define __BREAKPOINT()			\
williamr@2: 	{							\
williamr@2: 	__asm { int 3 };			\
williamr@2: 	}
williamr@2: #endif //__CW32__
williamr@2: #else
williamr@2: /** 
williamr@2: @internalAll
williamr@2: @released
williamr@2: */
williamr@2: #define __BREAKPOINT()
williamr@2: #endif
williamr@2: 
williamr@2: #if defined(_DEBUG)
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Asserts that a condition is true.
williamr@2: 
williamr@2: Code is generated for debug builds only.
williamr@2: 
williamr@2: This macro is used as a C++ statement to assert the truth of some condition,
williamr@2: and to take appropriate action if the condition is false. It is used in
williamr@2: the same way as __ASSERT_ALWAYS, except that it is only defined for debug builds.
williamr@2: 
williamr@2: The macro may be used to insert extra checks at various points in source code
williamr@2: as desired; the code will only be generated in debug builds and not in release
williamr@2: builds.
williamr@2: 
williamr@2: @param c A conditional expression which results in true or false.
williamr@2: @param p A function which is called if the conditional expression c is false.
williamr@2: 
williamr@2: @see __ASSERT_ALWAYS
williamr@2: */
williamr@2: #define __ASSERT_DEBUG(c,p) (void)((c)||(p,0))
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: @internalAll
williamr@2: @removed
williamr@2: */
williamr@2: #define __DECLARE_NAME(t)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Calls the function for testing object invariance.
williamr@2: 
williamr@2: Classes can define a standard member function __DbgTestInvariant(),
williamr@2: which checks that the object is in a valid state, and panics if it is not.
williamr@2: In debug builds, this macro simply expands to call that function. For details on how
williamr@2: to define __DbgTestInvariant(), and an example of its use, see __DECLARE_TEST.
williamr@2: 
williamr@2: The macro is typically invoked at the beginning of all the member functions of
williamr@2: the class. For non-const functions (those which can change the object’s state),
williamr@2: you can ensure that the object has been left in a stable state by invoking
williamr@2: the macro at the end of the function.
williamr@2: 
williamr@2: In release builds, no code is generated for the macro. 
williamr@2: */
williamr@2: #define __TEST_INVARIANT __DbgTestInvariant()
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the start of checking the current thread's heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must be matched by a corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
williamr@2: 
williamr@2: Calls to this macro can be nested but each call must be matched by corresponding 
williamr@2: call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
williamr@2: 
williamr@2: @see User::__DbgMarkStart()
williamr@2: @see __UHEAP_MARKEND
williamr@2: @see __UHEAP_MARKENDC
williamr@2: */
williamr@2: #define __UHEAP_MARK User::__DbgMarkStart(FALSE)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the number of allocated cells at the current nested level on the 
williamr@2: current thread's heap is the same as the specified value.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: The macro assumes that:
williamr@2: 
williamr@2: 1. the heap being checked is a user heap
williamr@2: 
williamr@2: 2. checking is being done for the number of allocated cells at the current nested 
williamr@2:    level; i.e. that aCountAll is set to false
williamr@2: 
williamr@2: 3. the line number is the line number of this source code statement.
williamr@2: 
williamr@2: 4. the file name is the full path name of the file containing this source statement
williamr@2: 
williamr@2: @param aCount The number of heap cells expected to be allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see User::__DbgMarkCheck()
williamr@2: @see __KHEAP_CHECK
williamr@2: */
williamr@2: #define __UHEAP_CHECK(aCount) User::__DbgMarkCheck(FALSE,FALSE,aCount,(TText8*)__FILE__,__LINE__)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the total number of allocated cells on the current thread's heap 
williamr@2: is the same as the specified value.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: @param aCount The total number of heap cells expected to be allocated.
williamr@2: 
williamr@2: @see User::__DbgMarkCheck()
williamr@2: @see __KHEAP_CHECKALL
williamr@2: */
williamr@2: #define __UHEAP_CHECKALL(aCount) User::__DbgMarkCheck(FALSE,TRUE,aCount,(TText8*)__FILE__,__LINE__)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of checking the current thread's heap. 
williamr@2: 
williamr@2: The macro expects zero heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __UHEAP_MARK.
williamr@2: 
williamr@2: @see User::__DbgMarkEnd()
williamr@2: @see __UHEAP_MARK
williamr@2: */
williamr@2: #define __UHEAP_MARKEND User::__DbgMarkEnd(FALSE,0)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of checking the current thread's heap. 
williamr@2: 
williamr@2: The macro expects aCount heap cells to remain allocated at the current nest 
williamr@2: level.
williamr@2: 
williamr@2: This macro must match an earlier call to __UHEAP_MARK.
williamr@2: 
williamr@2: @param aCount The number of heap cells expected to remain allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see User::__DbgMarkEnd()
williamr@2: @see __UHEAP_MARK
williamr@2: */
williamr@2: #define __UHEAP_MARKENDC(aCount) User::__DbgMarkEnd(FALSE,aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aCount Determines when the allocation will fail.
williamr@2:               Heap allocation fails on attempt number aCount - later
williamr@2:               allocations will succeed.
williamr@2:               For example, if aCount is 3, then heap allocation fails
williamr@2:               on the 3rd attempt, but all subsequent allocations succeed. 
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_FAILNEXT(aCount) User::__DbgSetAllocFail(FALSE,RAllocator::EFailNext,aCount)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap.
williamr@2: 
williamr@2: The failures will occur for aBurst times from the next call to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aCount Determines when the allocation will fail.
williamr@2:               Heap allocation fails on attempt number aCount - later
williamr@2:               allocations will succeed.
williamr@2:               For example, if aCount is 3, then heap allocation fails
williamr@2:               on the 3rd attempt, but all subsequent allocations succeed.  
williamr@2:               Note when used with RHeap the maximum value aCount can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set to 
williamr@2:               is KMaxTUint16.
williamr@2: 
williamr@2: @see User::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_BURSTFAILNEXT(aCount,aBurst) User::__DbgSetBurstAllocFail(FALSE,RAllocator::EBurstFailNext,aCount,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aType  The type of failure to be simulated.
williamr@2: @param aRate The failure rate.
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __UHEAP_SETFAIL(aType,aRate) User::__DbgSetAllocFail(FALSE, aType, aRate)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aType  The type of failure to be simulated.
williamr@2: @param aRate  The failure rate.  Note when used with RHeap the maximum value 
williamr@2:               aRate can be set to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.    Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see User::__DbgSetBurstAllocFail()
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __UHEAP_SETBURSTFAIL(aType,aRate,aBurst) User::__DbgSetBurstAllocFail(FALSE, aType, aRate, aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_RESET User::__DbgSetAllocFail(FALSE,RAllocator::ENone,1)
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated heap allocation failure for the current thread's heap. 
williamr@2: It walks the the heap and sets the nesting level for all allocated
williamr@2: cells to zero.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: */
williamr@2: #define __UHEAP_TOTAL_RESET User::__DbgSetAllocFail(FALSE,RAllocator::EReset,1)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of heap allocation failures the current debug allocator fail
williamr@2: function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __UHEAP_CHECKFAILURE User::__DbgCheckFailure(FALSE)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of kernel heap allocation failures the current debug 
williamr@2: allocator fail function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __KHEAP_CHECKFAILURE User::__DbgCheckFailure(TRUE)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the start of heap checking for the specific heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must be matched by a corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
williamr@2: 
williamr@2: Calls to this macro can be nested but each call must be matched by corresponding 
williamr@2: call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap
williamr@2: 
williamr@2: @see RHeap
williamr@2: @see RAllocator::__DbgMarkStart()
williamr@2: @see __RHEAP_MARKEND
williamr@2: @see __RHEAP_MARKENDC
williamr@2: */
williamr@2: #define __RHEAP_MARK(aHeap) (aHeap)->__DbgMarkStart()
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the number of allocated cells at the current nested level on the 
williamr@2: specified heap is the same as the specified value. 
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The number of heap cells expected to be allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkCheck()
williamr@2: */
williamr@2: #define __RHEAP_CHECK(aHeap,aCount) (aHeap)->__DbgMarkCheck(FALSE,aCount,(TText8*)__FILE__,__LINE__)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the total number of allocated cells on the specified heap is the 
williamr@2: same as the specified value.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The total number of heap cells expected to be allocated.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkCheck()
williamr@2: */
williamr@2: #define __RHEAP_CHECKALL(aHeap,aCount) (aHeap)->__DbgMarkCheck(TRUE,aCount,(TText8*)__FILE__,__LINE__)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of heap checking for the specific heap.
williamr@2: 
williamr@2: The macro expects zero heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __RHEAP_MARK.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkEnd()
williamr@2: @see __RHEAP_MARK
williamr@2: */
williamr@2: #define __RHEAP_MARKEND(aHeap) (aHeap)->__DbgMarkEnd(0)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of heap checking for the specific heap.
williamr@2: 
williamr@2: The macro expects aCount heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __RHEAP_MARK.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The number of heap cells expected to remain allocated at
williamr@2:               the current nest level
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkEnd()
williamr@2: @see __RHEAP_MARK
williamr@2: */
williamr@2: #define __RHEAP_MARKENDC(aHeap,aCount) (aHeap)->__DbgMarkEnd(aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which allocate 
williamr@2: memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The rate of failure - heap allocation fails every aCount attempt.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_FAILNEXT(aHeap,aCount) (aHeap)->__DbgSetAllocFail(RAllocator::EFailNext,aCount)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates aBurst allocation failures for the specific heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which allocate 
williamr@2: memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The heap allocation will fail after aCount-1 allocation attempts. 
williamr@2:               Note when used with RHeap the maximum value aCount can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_BURSTFAILNEXT(aHeap,aCount,aBurst) (aHeap)->__DbgSetBurstAllocFail(RAllocator::EBurstFailNext,aCount, aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aType  The type of failure to be simulated. 
williamr@2: @param aRate The failure rate.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_SETFAIL(aHeap,aType,aRate) (aHeap)->__DbgSetAllocFail(aType,aRate)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aType  The type of failure to be simulated. 
williamr@2: @param aRate  The failure rate.  Note when used with RHeap the maximum value 
williamr@2:               aRate can be set to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_SETBURSTFAIL(aHeap,aType,aRate,aBurst) (aHeap)->__DbgSetBurstAllocFail(aType,aRate,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated allocation failure for the specific heap.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_RESET(aHeap) (aHeap)->__DbgSetAllocFail(RAllocator::ENone,1)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated allocation failure for the specific heap.
williamr@2: It walks the the heap and sets the nesting level for all allocated
williamr@2: cells to zero.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_TOTAL_RESET(aHeap) (aHeap)->__DbgSetAllocFail(RAllocator::EReset,1)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of heap allocation failures the current debug allocator fail
williamr@2: function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __RHEAP_CHECKFAILURE(aHeap) (aHeap)->__DbgCheckFailure()
williamr@2: 
williamr@2: 
williamr@2: #if defined (__WINS__) 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __DEBUGGER() {if (User::JustInTime()) __BREAKPOINT()}
williamr@2: 
williamr@2: #else
williamr@2: #define __DEBUGGER()
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: #if defined(__DLL__)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Declares a function for testing object invariance.
williamr@2: 
williamr@2: For complex classes, it is often useful to provide a function that can
williamr@2: be called to check that the object is in a valid state.
williamr@2: The __DECLARE_TEST macro supplies a standard prototype for such a function
williamr@2: named __DbgTestInvariant(). A companion macro __TEST_INVARIANT is provided
williamr@2: to call the function.
williamr@2: 
williamr@2: For DLLs, as opposed to EXEs, __DbgTestInvariant() is exported,
williamr@2: i.e. the macro expands to:
williamr@2: 
williamr@2: @code
williamr@2: public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
williamr@2: @endcode
williamr@2: 
williamr@2: This macro should placed as the last item in a class declaration (as it 
williamr@2: switches back to public access). Note that a terminating semi-colon must be used.
williamr@2: 
williamr@2: You should define the __DbgTestInvariant() function to check that the object
williamr@2: is in a healthy state. If it finds an error, it should call User::Invariant(),
williamr@2: which will cause a panic. 
williamr@2: 
williamr@2: If a class is derived from a base class, then the base class __DbgTestInvariant()
williamr@2: should be called first, and then any further checking done. 
williamr@2: 
williamr@2: The second function declared, __DbgTest(), is intended to allow test code a way
williamr@2: of directly accessing non-public members of a class. The function is
williamr@2: implemented by any test code that requires it, rather than in the class’s own
williamr@2: source code. The function is therefore not exported.
williamr@2: 
williamr@2: __DECLARE_TEST is defined for both debug and release builds. This point is
williamr@2: particularly important for DLLs, as otherwise the exported interfaces would
williamr@2: differ between the build versions, giving potential binary compatibility
williamr@2: problems. To avoid using memory unnecessarily in release builds, you can,
williamr@2: however, use preprocessor directives to define the code within
williamr@2: __DbgTestInvariant() only for debug builds. __DbgTestInvariant() is never
williamr@2: called in release builds.
williamr@2: 
williamr@2: @see __TEST_INVARIANT
williamr@2: */
williamr@2: #define __DECLARE_TEST public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
williamr@2: #else
williamr@2: #define __DECLARE_TEST public: void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
williamr@2: #endif
williamr@2: 
williamr@2: #else
williamr@2: #define __ASSERT_DEBUG(c,p)
williamr@2: #define __DECLARE_NAME(t)
williamr@2: #define __TEST_INVARIANT
williamr@2: #if defined(__DLL__)
williamr@2: #define __DECLARE_TEST public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
williamr@2: #else
williamr@2: #define __DECLARE_TEST public: void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the start of checking the current thread's heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must be matched by a corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
williamr@2: 
williamr@2: Calls to this macro can be nested but each call must be matched by corresponding 
williamr@2: call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
williamr@2: 
williamr@2: @see User::__DbgMarkStart()
williamr@2: @see __UHEAP_MARKEND
williamr@2: @see __UHEAP_MARKENDC
williamr@2: */
williamr@2: #define __UHEAP_MARK
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the number of allocated cells at the current nested level on the 
williamr@2: current thread's heap is the same as the specified value.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: The macro assumes that:
williamr@2: 
williamr@2: 1. the heap being checked is a user heap
williamr@2: 
williamr@2: 2. checking is being done for the number of allocated cells at the current nested 
williamr@2:    level; i.e. that aCountAll is set to false
williamr@2: 
williamr@2: 3. the line number is the line number of this source code statement.
williamr@2: 
williamr@2: 4. the file name is the full path name of the file containing this source statement
williamr@2: 
williamr@2: @param aCount The number of heap cells expected to be allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see User::__DbgMarkCheck()
williamr@2: @see __KHEAP_CHECK
williamr@2: */
williamr@2: #define __UHEAP_CHECK(aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the total number of allocated cells on the current thread's heap 
williamr@2: is the same as the specified value.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: @param aCount The total number of heap cells expected to be allocated.
williamr@2: 
williamr@2: @see User::__DbgMarkCheck()
williamr@2: @see __KHEAP_CHECKALL
williamr@2: */
williamr@2: #define __UHEAP_CHECKALL(aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of checking the current thread's heap. 
williamr@2: 
williamr@2: The macro expects zero heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __UHEAP_MARK.
williamr@2: 
williamr@2: @see User::__DbgMarkEnd()
williamr@2: @see __UHEAP_MARK
williamr@2: */
williamr@2: #define __UHEAP_MARKEND
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of checking the current thread's heap. 
williamr@2: 
williamr@2: The macro expects aCount heap cells to remain allocated at the current nest 
williamr@2: level.
williamr@2: 
williamr@2: This macro must match an earlier call to __UHEAP_MARK.
williamr@2: 
williamr@2: @param aCount The number of heap cells expected to remain allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see User::__DbgMarkEnd()
williamr@2: @see __UHEAP_MARK
williamr@2: */
williamr@2: #define __UHEAP_MARKENDC(aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aCount Determines when the allocation will fail.
williamr@2:               Heap allocation fails on attempt number aCount - later
williamr@2:               allocations will succeed.
williamr@2:               For example, if aCount is 3, then heap allocation fails
williamr@2:               on the 3rd attempt, but all subsequent allocations succeed. 
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_FAILNEXT(aCount)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap.
williamr@2: 
williamr@2: The failures will occur for aBurst times from the next call to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aCount Determines when the allocation will fail.
williamr@2:               Heap allocation fails on attempt number aCount - later
williamr@2:               allocations will succeed.
williamr@2:               For example, if aCount is 3, then heap allocation fails
williamr@2:               on the 3rd attempt, but all subsequent allocations succeed.   
williamr@2:               Note when used with RHeap the maximum value aBurst can be 
williamr@2:               set to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see User::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_BURSTFAILNEXT(aCount,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aType  The type of failure to be simulated.
williamr@2: @param aRate The failure rate.
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_SETFAIL(aType,aRate)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aType  The type of failure to be simulated.
williamr@2: @param aRate  The failure rate.  Note when used with RHeap the maximum value 
williamr@2:               aRate can be set to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see User::__DbgSetBurstAllocFail()
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __UHEAP_SETBURSTFAIL(aType,aRate,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated heap allocation failure for the current thread's heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @see User::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __UHEAP_RESET
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated heap allocation failure for the current thread's heap. 
williamr@2: It walks the the heap and sets the nesting level for all allocated
williamr@2: cells to zero.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: */
williamr@2: #define __UHEAP_TOTAL_RESET
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of heap allocation failures the current debug allocator fail
williamr@2: function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __UHEAP_CHECKFAILURE ((TUint)0)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of kernel heap allocation failures the current debug 
williamr@2: allocator fail function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __KHEAP_CHECKFAILURE ((TUint)0)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the start of heap checking for the specific heap. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must be matched by a corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
williamr@2: 
williamr@2: Calls to this macro can be nested but each call must be matched by corresponding 
williamr@2: call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap
williamr@2: 
williamr@2: @see RHeap
williamr@2: @see RAllocator::__DbgMarkStart()
williamr@2: @see __RHEAP_MARKEND
williamr@2: @see __RHEAP_MARKENDC
williamr@2: */
williamr@2: #define __RHEAP_MARK(aHeap)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the number of allocated cells at the current nested level on the 
williamr@2: specified heap is the same as the specified value. 
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail. 
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The number of heap cells expected to be allocated at
williamr@2:               the current nest level.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkCheck()
williamr@2: */
williamr@2: #define __RHEAP_CHECK(aHeap,aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Checks that the total number of allocated cells on the specified heap is the 
williamr@2: same as the specified value.
williamr@2: 
williamr@2: The macro also takes the name of the file containing this source code statement 
williamr@2: and the line number of this source code statement; they are displayed as part 
williamr@2: of the panic category, if the checks fail.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The total number of heap cells expected to be allocated.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkCheck()
williamr@2: */
williamr@2: #define __RHEAP_CHECKALL(aHeap,aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of heap checking for the specific heap.
williamr@2: 
williamr@2: The macro expects zero heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __RHEAP_MARK.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkEnd()
williamr@2: @see __RHEAP_MARK
williamr@2: */
williamr@2: #define __RHEAP_MARKEND(aHeap)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Marks the end of heap checking for the specific heap.
williamr@2: 
williamr@2: The macro expects aCount heap cells to remain allocated at the current nest 
williamr@2: level. This macro is defined only for debug builds.
williamr@2: 
williamr@2: This macro must match an earlier call to __RHEAP_MARK.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The number of heap cells expected to remain allocated at
williamr@2:               the current nest level
williamr@2: 
williamr@2: @see RAllocator::__DbgMarkEnd()
williamr@2: @see __RHEAP_MARK
williamr@2: */
williamr@2: #define __RHEAP_MARKENDC(aHeap,aCount)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which allocate 
williamr@2: memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The rate of failure - heap allocation fails every aCount attempt.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_FAILNEXT(aHeap,aCount)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates aBurst allocation failures for the specific heap.
williamr@2: 
williamr@2: The failure occurs on the next call to new or any of the functions which allocate 
williamr@2: memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aCount The heap allocation will fail after aCount-1 allocation attempts. 
williamr@2:               Note when used with RHeap the maximum value aCount can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_BURSTFAILNEXT(aHeap,aCount,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aType  The type of failure to be simulated. 
williamr@2: @param aRate The failure rate.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_SETFAIL(aHeap,aType,aRate)
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Simulates an allocation failure for the specific heap. 
williamr@2: 
williamr@2: The failure occurs on subsequent calls to new or any of the functions which 
williamr@2: allocate memory from the heap. This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap  A pointer to the specific RHeap.
williamr@2: @param aType  The type of failure to be simulated. 
williamr@2: @param aRate  The failure rate.  Note when used with RHeap the maximum value 
williamr@2:               aRate can be set to is KMaxTUint16.
williamr@2: @param aBurst The number of consecutive allocations that will fail.  Note 
williamr@2:               when used with RHeap the maximum value aBurst can be set 
williamr@2:               to is KMaxTUint16.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetBurstAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_SETBURSTFAIL(aHeap,aType,aRate,aBurst)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated allocation failure for the specific heap.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_RESET(aHeap)
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Cancels simulated allocation failure for the specific heap.
williamr@2: It walks the the heap and sets the nesting level for all allocated
williamr@2: cells to zero.
williamr@2: 
williamr@2: This macro is defined only for debug builds.
williamr@2: 
williamr@2: @param aHeap A pointer to the specific RHeap.
williamr@2: 
williamr@2: @see RAllocator::__DbgSetAllocFail()
williamr@2: */
williamr@2: #define __RHEAP_TOTAL_RESET(aHeap)
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Returns the number of heap allocation failures the current debug allocator fail
williamr@2: function has caused so far.
williamr@2: 
williamr@2: This is intended to only be used with fail types RAllocator::EFailNext,
williamr@2: RAllocator::EBurstFailNext, RAllocator::EDeterministic and
williamr@2: RAllocator::EBurstDeterministic.  The return value is unreliable for 
williamr@2: all other fail types.
williamr@2: 
williamr@2: @return The number of heap allocation failures the current debug fail 
williamr@2: function has caused.
williamr@2: 
williamr@2: @see RAllocator::TAllocFail
williamr@2: */
williamr@2: #define __RHEAP_CHECKFAILURE(aHeap) ((TUint)0)
williamr@2: 
williamr@2: #define __DEBUGGER()
williamr@2: #endif
williamr@2: 
williamr@2: #if defined (__WINS__)
williamr@2: /** @internalTechnology */
williamr@2: #define __EMULATOR_IMAGE_HEADER2(aUid0,aUid1,aUid2,aPriority,aCap0,aCap1,aSid,aVid,aVer,aFlags)	TEmulatorImageHeader uid={{aUid0,aUid1,aUid2},aPriority,{aSid,aVid,{aCap0,aCap1}},0,0,aVer,aFlags};
williamr@2: /** @internalTechnology */
williamr@2: #define __EMULATOR_IMAGE_HEADER(aUid0,aUid1,aUid2,aPriority,aCap,aFlags)					TEmulatorImageHeader uid={{aUid0,aUid1,aUid2},aPriority,{aUid2,0,{aCap,0}},0,0,0x00010000u,aFlags};
williamr@2: #else
williamr@2: #define __EMULATOR_IMAGE_HEADER2(aUid0,aUid1,aUid2,aPriority,aCap0,aCap1,aSid,aVer,aFlags)
williamr@2: #define __EMULATOR_IMAGE_HEADER(aUid0,aUid1,aUid2,aPriority,aCap,aFlags)
williamr@2: #endif
williamr@2: 
williamr@2: #if defined(_UNICODE)
williamr@2: #if !defined(UNICODE)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: #define UNICODE
williamr@2: #endif
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(ASSERT)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Generates _ASSERT_DEBUG code that calls User::Invariant() if the specified
williamr@2: condition is not true.
williamr@2: 
williamr@2: @param x A conditional expression which results in true or false.
williamr@2: */
williamr@2: #define ASSERT(x) __ASSERT_DEBUG(x,User::Invariant())
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #if defined(_DEBUG)
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #define __DEBUG_ONLY(x) x
williamr@2: #else
williamr@2: #define __DEBUG_ONLY(x)
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifdef __KERNEL_MODE__
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define	KIMPORT_C	IMPORT_C
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define	KEXPORT_C	EXPORT_C
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define	UIMPORT_C
williamr@2: 
williamr@2: /** @internalComponent */
williamr@2: #define	UEXPORT_C
williamr@2: #else
williamr@2: #define	KIMPORT_C
williamr@2: #define	KEXPORT_C
williamr@2: #define	UIMPORT_C	IMPORT_C
williamr@2: #define	UEXPORT_C	EXPORT_C
williamr@2: #endif
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: 
williamr@2: Asserts that a condition is true at compilation time.
williamr@2: 
williamr@2: @param x Condition to assert
williamr@2: */
williamr@2: #define __ASSERT_COMPILE(x)		void __compile_time_assert(int __check[(x)?1:-1])
williamr@2: 
williamr@2: #ifdef __REMOVE_PLATSEC_DIAGNOSTICS__
williamr@2: /**
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: */
williamr@2: #ifndef __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
williamr@2: #define __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
williamr@2: #endif /*__REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__*/
williamr@2: #endif /*__REMOVE_PLATSEC_DIAGNOSTICS__*/
williamr@2: 
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: static const char* const KSuppressPlatSecDiagnosticMagicValue = (const char*)1;
williamr@2: 
williamr@2: #ifndef __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER(l) #l
williamr@2: /**
williamr@2: @internalComponent
williamr@2: */
williamr@2: #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER2(f,l) f "(" __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER(l) ")"
williamr@2: /**
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: */
williamr@2: #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER2(__FILE__,__LINE__)
williamr@2: 
williamr@2: /**
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: 
williamr@2: A macro that should be used to enclose a platform security diagnostic
williamr@2: 'C' style string that can be passed to a capability checking function such
williamr@2: as RThread::HasCapability() and Kern::CurrentThreadHasCapability().
williamr@2: 
williamr@2: The content of the string is emitted if the capability test finds that
williamr@2: the capability is not present.
williamr@2: 
williamr@2: The macro provides a convenient mechanism that allows the strings to
williamr@2: be removed from future versions of Symbian OS.
williamr@2: 
williamr@2: For example:
williamr@2: 
williamr@2: @code
williamr@2: if(!Kern::CurrentThreadHasCapability(ECapabilityPowerMgmt,__PLATSEC_DIAGNOSTIC_STRING("Checked by Hal function EDisplayHalSetState")))
williamr@2:     {
williamr@2:     return KErrPermissionDenied;
williamr@2:     }			
williamr@2: @endcode
williamr@2: 
williamr@2: In this example, the string:
williamr@2: 
williamr@2: @code
williamr@2: Checked by Hal function EDisplayHalSetState
williamr@2: @endcode
williamr@2: 
williamr@2: is emitted if the calling process does not have the ECapabilityPowerMgmt capability.
williamr@2: 
williamr@2: @param s A C-style string.
williamr@2: 
williamr@2: @see RProcess::HasCapability()
williamr@2: @see RThread::HasCapability()
williamr@2: @see RMessagePtr2::HasCapability()
williamr@2: @see User::CreatorHasCapability()
williamr@2: */
williamr@2: #define __PLATSEC_DIAGNOSTIC_STRING(s) s
williamr@2: 
williamr@2: /**
williamr@2: When this value is used in Platform Security APIs as the value for the aDiagnosticText
williamr@2: argument, these APIs will not emit any form of diagnostic message.
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: */
williamr@2: // Note this value is the same as KSuppressPlatSecDiagnosticMagicValue
williamr@2: // and used to be a set by it but that caused an error with GCCE compiler
williamr@2: static const char* const KSuppressPlatSecDiagnostic = (const char*)1;
williamr@2: 
williamr@2: #else /* __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__ */
williamr@2: 
williamr@2: #define __PLATSEC_DIAGNOSTIC_STRING(s) NULL
williamr@2: 
williamr@2: #ifndef __KERNEL_MODE__
williamr@2: #ifndef __REMOVE_PLATSEC_DIAGNOSTICS__
williamr@2: /**
williamr@2: When this value is used in Platform Security APIs as the value for the aDiagnostic
williamr@2: argument, these APIs will not emit any form of diagnostic message.
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: */
williamr@2: #define KSuppressPlatSecDiagnostic		NULL, NULL
williamr@2: 
williamr@2: #else /* __REMOVE_PLATSEC_DIAGNOSTICS__ */
williamr@2: 
williamr@2: /**
williamr@2: When this value is used in Platform Security APIs as the value for the aDiagnostic
williamr@2: argument, these APIs will not emit any form of diagnostic message.
williamr@2: @publishedPartner
williamr@4: @released
williamr@2: */
williamr@2: #define KSuppressPlatSecDiagnostic		NULL
williamr@2: 
williamr@2: #endif /* !__REMOVE_PLATSEC_DIAGNOSTICS__ */
williamr@2: #endif /* !__KERNEL_MODE__ */
williamr@2: #endif /* !__REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__ */
williamr@2: 
williamr@2: /*
williamr@2:  * MSVC operator new and operator new[] header guards
williamr@2:  */
williamr@2: #ifdef __PLACEMENT_NEW
williamr@2: #define __PLACEMENT_NEW_INLINE
williamr@2: #endif /* __PLACEMENT_NEW */
williamr@2: 
williamr@2: #if defined(__VC32__) && (_MSC_VER < 1300)
williamr@2: #define __PLACEMENT_VEC_NEW_INLINE
williamr@4: #define __OMIT_VEC_OPERATOR_NEW_DECL__
williamr@2: #endif /* version of MSVC that doesn't support overloaded operator new[] */
williamr@2: 
williamr@2: /**
williamr@2: Calling convention qualifier for functions involving floating point 
williamr@2: variables passed or returned by value.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: #ifndef __SOFTFP
williamr@2: #define __SOFTFP
williamr@2: #endif /* __SOFTFP */
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <e32def_private.h>
williamr@4: #endif
williamr@4: 
williamr@2: #endif /* __E32DEF_H__ */