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(exp)) williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @deprecated williamr@2: */ williamr@2: #define STATIC_CAST(type,exp) (static_cast(exp)) williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @deprecated williamr@2: */ williamr@2: #define REINTERPRET_CAST(type,exp) (reinterpret_cast(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(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(&(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(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 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 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 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 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 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 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 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 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 williamr@4: #endif williamr@4: williamr@2: #endif /* __E32DEF_H__ */