e32def.h File Reference

__GNUC__

__NO_CLASS_CONSTS__

__NORETURN__

__NORETURN_TERMINATOR

IMPORT_C

IMPORT_D

EXPORT_C

EXPORT_D

NONSHARABLE_CLASS

NONSHARABLE_STRUCT

__NO_THROW

__THROW

TEMPLATE_SPECIALIZATION

__DOUBLE_WORDS_SWAPPED__

__NO_MUTABLE_KEYWORD

__MUTABLE

Deprecated

CONST_CAST

Deprecated

STATIC_CAST

Deprecated

REINTERPRET_CAST

Deprecated

MUTABLE_CAST

Deprecated

GLREF_D

Deprecated

GLDEF_D

Deprecated

LOCAL_D

Deprecated

GLREF_C

Deprecated

GLDEF_C

Deprecated

LOCAL_C

Deprecated

FOREVER

Deprecated

TRUE

Symbolic definition for a true value.

FALSE

Symbolic definition for a false value.

NULL

Symbolic definition for a NULL value.

VA_START

A macro used by Symbian OS code for handling a variable argument list in a function call.

Sets a pointer to point to the first of the variable arguments.

Typical usage:

Foo(CAbcdef aAbcdef,...)
   {
   VA_LIST list;
   VA_START(list, aAbcdef);
   // other code
   } 

See also: VA_LIST VA_ARG

VA_ARG

A macro used by Symbian OS code for handling a variable argument list in a function call.

Increments a pointer to a variable argument list to point to the next argument in the list. The current argument is assumed to be of a type defined by the second parameter to this macro.

Typical usage:

Foo(CAbcdef aAbcdef,...)
   {
   VA_LIST list;
   VA_START(list, aAbcdef);
   ...
   TInt x = VA_ARG(list,TInt);
   ...
   const TDesC *pS=VA_ARG(aList,const TDesC*);
   ... 
   etc
   } 

See also: VA_LIST VA_START

VA_END

A macro used by Symbian OS code for handling a variable argument list in a function call.

Sets a pointer to zero.

See also: VA_LIST VA_START VA_ARG

_FOFF_DYNAMIC

Calculates the offset of member f within class c.

This is used in the TSglQue and TDblQue constructors to set the offset of the link object from the start of a list element.

See also: TSglQue TDblQue

_FOFF

_ALIGN_DOWN

_ALIGN_UP

Typedef TAny

typedef voidTAny

Pointer to any type.

TAny* is equivalent to void* in standard C or C++. TAny* is used in preference to void* because it is more suggestive of the actual meaning, e.g. TAny* foo();.

TAny is not used where it really means "nothing", as in the declaration of functions which do not return a value; void is used instead, e.g. void Foo();.

Typedef TInt8

typedef signed charTInt8

8-bit signed integer type, used in Symbian OS to mean an 8-bit signed integer, independent of the implementation.

Typedef TUint8

typedef unsigned charTUint8

8-bit unsigned integer type; used in Symbian OS to mean an 8-bit unsigned integer, independent of the implementation.

Typedef TInt16

typedef short intTInt16

16-bit signed integer type, used in Symbian OS to mean a 16-bit signed integer, independent of the implementation.

Typedef TUint16

typedef unsigned short intTUint16

16-bit unsigned integer type. used in Symbian OS to mean a 16-bit unsigned integer, independent of the implementation.

Typedef TInt32

typedef long intTInt32

32-bit signed integer type, used in Symbian OS to mean a 32-bit signed integer, independent of the implementation.

Typedef T_IntPtr

typedef TInt32 T_IntPtr

A signed integer type of the same size as a pointer.

Typedef TIntPtr

typedef TInt32 TIntPtr

Typedef TUint32

typedef unsigned long intTUint32

32-bit unsigned integer type; used in Symbian OS to mean a 32-bit unsigned integer, independent of the implementation.

Typedef T_UintPtr

typedef TUint32 T_UintPtr

An unsigned integer type of the same size as a pointer.

Typedef TUintPtr

typedef TUint32 TUintPtr

Typedef TInt

typedef signed intTInt

Signed integer type of the natural machine word length.

This is as defined by the C++ implementation's int type. In all implementations, this is guaranteed to be at least 32 bits.

A TInt should be used in preference to a sized integer (TInt32, TInt16) for all general use. Sized integers should only be used when packing is essential. C++'s type conversion rules imply that all sized integers smaller than the natural machine word are in any case broadened to the natural machine word size when passed as function parameters.

A TInt should be used in preference to an unsigned integer (TUint) for all general use. Unsigned integers should only be used for flags (which use Boolean operations but not arithmetic) and, in very rare cases, for numbers whose range exceeds that available from signed integers. Although it is natural to attempt to use unsigned integers for quantities which cannot by nature be negative, the C++ language does not provide the support necessary to enforce the "expected" behaviour in these circumstances, and experience has shown that it is better to use signed integers unless there is good reason not to.

See also: TUint TInt32 TInt16

Typedef TUint

typedef unsigned intTUint

Unsigned integer type of the natural machine word length.

This is guaranteed to be at least 32 bits in all implementations.

In almost all circumstances, a TInt should be used in preference to a TUint. The main exception is in flags bytes.

See also: TInt

Typedef TReal32

typedef floatTReal32

32-bit floating point number, providing IEEE754 single precision on all Symbian OS implementations.

TReal should normally be used in preference to TReal32.

Use of floating-point numbers should generally be avoided unless a natural part of the problem specification. Most Symbian OS implementations do not have a hardware floating point unit: as a result, their floating-point performance is hundreds of times slower than integer performance.

Typedef TReal64

typedef doubleTReal64

64-bit floating point number, providing IEEE754 double precision on all Symbian OS implementations.

Use of floating-point numbers should generally be avoided unless a natural part of the problem specification. Most Symbian OS implementations do not have a hardware floating point unit: as a result, their floating-point performance is hundreds of times slower than integer performance.

This type is identical to TReal.

See also: TReal

Typedef TReal

typedef doubleTReal

64-bit floating point number; identical to TReal64.

Use of floating-point numbers should generally be avoided unless a natural part of the problem specification. Most Symbian OS implementations do not have a hardware floating point unit: as a result, their floating-point performance is hundreds of times slower than integer performance.

Most serious floating-point calculations require double-precision. All standard math functions (see Math class) take double-precision arguments. Single-precision should only be used where space and performance are at a premium, and when their limited precision is acceptable.

See also: TReal64 Math

Typedef TText8

typedef unsigned charTText8

8-bit unsigned character.

Use instead of C++ built-in char type because it is guaranteed to be unsigned. Use instead of TInt8 where the application is really for text rather than 8-bit arithmetic or binary quantities.

For most purposes, you should use TText rather than TText8. TText is mapped onto either TText8 or TText16 depending on whether a non-Unicode or Unicode variant is being built. Use TText8 only when you are dealing explicitly with 8-bit text, regardless of build.

See also: TText

Typedef TText16

typedef unsigned short intTText16

16-bit unsigned character.

Use instead of C++ wchar_t type because it is guaranteed to be unsigned. Use instead of TInt16 where the application is really for text rather than 8-bit arithmetic or binary quantities.

For most purposes, you should use TText rather than TText16. TText is mapped onto either TText8 or TText16 depending on whether a non-Unicode or Unicode variant is being built. Use TText16 only when you are dealing explicitly with 16-bit text, regardless of build.

See also: TText

Typedef TBool

typedef int TBool

Integer type representing true or false.

False is always represented by 0; any non-zero value is true.

Values of type TBool must never be compared against ETrue; so instead of

TBool foo(void);

if (foo() == ETrue) bar();

use

TBool foo(void);

if (foo()) bar();

And, instead of '!= ETrue' use '== EFalse' or the following (preferred):

TBool this(void);

if (!this()) that();

When returning a TBool, rather than

TBool List::IsEmpty(void)
	{
	return iAnchor == NULL ? ETrue : EFalse;
	}

use

TBool List::IsEmpty(void)
	{
	return iAnchor == NULL;
	}

and rather than

TBool SerialPort::DataPresent(void)
	{
	// Fictitious example
	volatile TUint *statusReg = (TUint *)0x1000;

	if ((*statusReg & 0x00FF0000) != 0)
		return ETrue;
	else
		return EFalse;
	}

use

TBool SerialPort::DataPresent(void)
	{
	// Fictitious example
	volatile TUint *statusReg = (TUint *)0x1000;

	return *statusReg & 0x00FF0000;
	}

See also: EFalse ETrue

Typedef TLinAddr

typedef T_UintPtr TLinAddr

Defines a linear (virtual) address type.

Typedef Int64

typedef long longInt64

Defines a 64-bit signed integer type.

Typedef Uint64

typedef unsigned long longUint64

Defines a 64-bit unsigned integer type.

I64LIT

UI64LIT

Typedef TInt64

typedef Int64 TInt64

Defines a 64-bit signed integer type.

NOTE: For those migrating from versions of Symbian OS before 8.1b (i.e. 8.1a, 7.0s etc) TInt64 is now defined as a built-in type instead of as a class type. This means that the member functions of the old TInt64 class are no longer exported from EUSER.LIB, and represents a compatibility break.

To ease migration of source code, a number of macros are provided. Similar macros have also been defined in Symbian OS versions 7.0s and 8.1a, but implemented in terms of the old TInt64 class. This is important for code that is common to : one or both of these Symbian OS versions, and to 8.1b and subsequent versions.

The following list shows the new macros and the functions that they replace. It also shows some alternative techniques. In this list: x, v and r are declared as TInt64, c is declared as TInt, High and Low are declared as TUint.

OLD USAGE						REPLACEMENT

TInt64(High,Low);				MAKE_TINT64(High,Low);
x.Set(High,Low);				MAKE_TINT64(High,Low);
x.Low();						I64LOW(x);
x.High();						I64HIGH(x); 
x.GetTInt();					I64INT(x); 
x.GetTReal();					I64REAL(x); 
x.Lsr(c);						I64LSR(x,c); 
x.Mul10();						x*=10; 
x.MulTop(a);					I64MULTOP(x,a); 
x.DivMod(v,r);					r=x%v; x/=v;

Typedef TUint64

typedef Uint64 TUint64

Defines a 64-bit unsigned integer type.

_MAKE_TINT64_ZX

_MAKE_TUINT64_ZX

MAKE_TINT64

MAKE_TUINT64

I64HIGH

Generates code to access the high order 32 bits of a 64 bit number.

I64LOW

Generates code to access the low order 32 bits of a 64 bit number.

I64INT

Generates code to cast a 64 bit value as an signed integer.

I64REAL

Generates code to cast a 64 bit value as a TReal type.

I64LSR

Generates code to logically shift a 64 bit integer right.

I64MUL10

Generates code to multiply a 64 bit integer by 10.

I64DIVMOD

Generates code to divide a 64 bit integer by another and find the remainder.

I64DOUBLECAST

Generates code to cast a double to a 64 bit integer.

_L8

DeprecatedUse _LIT8 instead.

8-bit literal.

The macro defines an explicit 8-bit constant literal which is suitable for non-Unicode literal text, regardless of the build.

See also: _L _LIT8 _LIT

_S8

Defines an explicit 8-bit string which is suitable when non-Unicode text is required, regardless of the build.

This is used by the deprecated literal descriptor _L8.

_LIT8

Constructs a constant literal descriptor of type TLitC8<TInt> with the specified name and text.

The 8-bit build variant is generated for both non-Unicode and Unicode builds.

See also: _LIT

_L16

DeprecatedUse _LIT16 instead.

16-bit literal.

The macro defines an explicit 16-bit constant literal which is suitable for Unicode literal text, regardless of the build.

See also: _L _LIT16 _LIT

_S16

Defines an explicit 16-bit string which is suitable when Unicode text is required, regardless of the build.

This is used by the deprecated literal descriptor _L16.

_LIT16

Constructs a constant literal descriptor of type TLitC16<TInt> with the specified name and text.

The 16-bit build variant is generated for both non-Unicode and Unicode builds.

See also: _LIT

Typedef TText

typedef TText16 TText

Build independent general text character.

In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is mapped to TText16. Use the classes with explicit width only when you wish the width to be independent of the build variant.

Use this class rather than TChar for general use.

_L

DeprecatedUse _LIT instead.

Build independent literal.

The macro defines either an 8-bit constant literal (for non-Unicode text), or a 16-bit constant literal (for Unicode text) depending on the build.

See also: _LIT _L16 _L8

_S

Defines either an 8-bit string (for non-Unicode text), or a 16-bit string (for Unicode text) depending on the build.

This is used by the deprecated build independent literal _L.

_LIT

Constructs a build independent constant literal descriptor of type TLitC<TInt> with the specified name and text.

An 8-bit build variant is generated for a non-Unicode build; A 16-bit build variant is generated for a Unicode build.

See also: _LIT16 _LIT8

Typedef VA_LIST

typedef TInt8 *VA_LIST

Defines a 'C' style array of pointers to TInt8 types.

The type is most commonly used by code that needs to deal with a variable number of arguments passed to a function.

See also: TInt8

__ASSERT_ALWAYS

Asserts that a condition is true.

Code is generated for all builds.

This macro is used as a C++ statement to assert the truth of some condition, and to take appropriate action if the condition is false. Unlike __ASSERT_DEBUG it is defined in both release and debug builds.

The most common use for this macro is to check that the external environment of a function or class is behaving as expected; for example, that parameters passed to a function are credible, or that called functions are behaving as expected; the macro is commonly placed at the beginning of a function.

The effect of the macro is to generate code which tests the conditional expression c; if the expression is false, then function p is called. In the majority of cases, the function p is one that raises a panic.

Note that the macro definition is, in effect, equivalent to:

if (!c)p;

See also: __ASSERT_DEBUG

__BREAKPOINT

__ASSERT_DEBUG

__DECLARE_NAME

__TEST_INVARIANT

__DECLARE_TEST

__UHEAP_MARK

Marks the start of checking the current thread's heap.

This macro is defined only for debug builds.

This macro must be matched by a corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.

Calls to this macro can be nested but each call must be matched by corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.

See also: User::__DbgMarkStart() __UHEAP_MARKEND __UHEAP_MARKENDC

__UHEAP_CHECK

Checks that the number of allocated cells at the current nested level on the current thread's heap is the same as the specified value.

This macro is defined only for debug builds.

The macro also takes the name of the file containing this source code statement and the line number of this source code statement; they are displayed as part of the panic category, if the checks fail.

The macro assumes that:

1. the heap being checked is a user heap

2. checking is being done for the number of allocated cells at the current nested level; i.e. that aCountAll is set to false

3. the line number is the line number of this source code statement.

4. the file name is the full path name of the file containing this source statement

See also: User::__DbgMarkCheck() __KHEAP_CHECK

__UHEAP_CHECKALL

Checks that the total number of allocated cells on the current thread's heap is the same as the specified value.

This macro is defined only for debug builds.

The macro also takes the name of the file containing this source code statement and the line number of this source code statement; they are displayed as part of the panic category, if the checks fail.

See also: User::__DbgMarkCheck() __KHEAP_CHECKALL

__UHEAP_MARKEND

Marks the end of checking the current thread's heap.

The macro expects zero heap cells to remain allocated at the current nest level. This macro is defined only for debug builds.

This macro must match an earlier call to __UHEAP_MARK.

See also: User::__DbgMarkEnd() __UHEAP_MARK

__UHEAP_MARKENDC

Marks the end of checking the current thread's heap.

The macro expects aCount heap cells to remain allocated at the current nest level.

This macro must match an earlier call to __UHEAP_MARK.

See also: User::__DbgMarkEnd() __UHEAP_MARK

__UHEAP_FAILNEXT

Simulates heap allocation failure for the current thread's heap.

The failure occurs on the next call to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: User::__DbgSetAllocFail()

__UHEAP_BURSTFAILNEXT

Simulates heap allocation failure for the current thread's heap.

The failures will occur for aBurst times from the next call to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: User::__DbgSetBurstAllocFail()

__UHEAP_SETFAIL

Simulates heap allocation failure for the current thread's heap.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: User::__DbgSetAllocFail()

__UHEAP_SETBURSTFAIL

Simulates heap allocation failure for the current thread's heap.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: User::__DbgSetBurstAllocFail() RAllocator::TAllocFail

__UHEAP_RESET

Cancels simulated heap allocation failure for the current thread's heap.

This macro is defined only for debug builds.

See also: User::__DbgSetAllocFail()

__UHEAP_TOTAL_RESET

Cancels simulated heap allocation failure for the current thread's heap. It walks the the heap and sets the nesting level for all allocated cells to zero.

This macro is defined only for debug builds.

__UHEAP_CHECKFAILURE

Returns the number of heap allocation failures the current debug allocator fail function has caused so far.

This is intended to only be used with fail types RAllocator::EFailNext, RAllocator::EBurstFailNext, RAllocator::EDeterministic and RAllocator::EBurstDeterministic. The return value is unreliable for all other fail types.

See also: RAllocator::TAllocFail

__KHEAP_CHECKFAILURE

Returns the number of kernel heap allocation failures the current debug allocator fail function has caused so far.

This is intended to only be used with fail types RAllocator::EFailNext, RAllocator::EBurstFailNext, RAllocator::EDeterministic and RAllocator::EBurstDeterministic. The return value is unreliable for all other fail types.

See also: RAllocator::TAllocFail

__RHEAP_MARK

Marks the start of heap checking for the specific heap.

This macro is defined only for debug builds.

This macro must be matched by a corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.

Calls to this macro can be nested but each call must be matched by corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.

See also: RHeap RAllocator::__DbgMarkStart() __RHEAP_MARKEND __RHEAP_MARKENDC

__RHEAP_CHECK

Checks that the number of allocated cells at the current nested level on the specified heap is the same as the specified value.

The macro also takes the name of the file containing this source code statement and the line number of this source code statement; they are displayed as part of the panic category, if the checks fail.

This macro is defined only for debug builds.

See also: RAllocator::__DbgMarkCheck()

__RHEAP_CHECKALL

Checks that the total number of allocated cells on the specified heap is the same as the specified value.

The macro also takes the name of the file containing this source code statement and the line number of this source code statement; they are displayed as part of the panic category, if the checks fail.

This macro is defined only for debug builds.

See also: RAllocator::__DbgMarkCheck()

__RHEAP_MARKEND

Marks the end of heap checking for the specific heap.

The macro expects zero heap cells to remain allocated at the current nest level. This macro is defined only for debug builds.

This macro must match an earlier call to __RHEAP_MARK.

See also: RAllocator::__DbgMarkEnd() __RHEAP_MARK

__RHEAP_MARKENDC

Marks the end of heap checking for the specific heap.

The macro expects aCount heap cells to remain allocated at the current nest level. This macro is defined only for debug builds.

This macro must match an earlier call to __RHEAP_MARK.

See also: RAllocator::__DbgMarkEnd() __RHEAP_MARK

__RHEAP_FAILNEXT

Simulates an allocation failure for the specific heap.

The failure occurs on the next call to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: RAllocator::__DbgSetAllocFail()

__RHEAP_BURSTFAILNEXT

Simulates aBurst allocation failures for the specific heap.

The failure occurs on the next call to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: RAllocator::__DbgSetBurstAllocFail()

__RHEAP_SETFAIL

Simulates an allocation failure for the specific heap.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: RAllocator::__DbgSetAllocFail()

__RHEAP_SETBURSTFAIL

Simulates an allocation failure for the specific heap.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from the heap. This macro is defined only for debug builds.

See also: RAllocator::__DbgSetBurstAllocFail()

__RHEAP_RESET

Cancels simulated allocation failure for the specific heap.

This macro is defined only for debug builds.

See also: RAllocator::__DbgSetAllocFail()

__RHEAP_TOTAL_RESET

Cancels simulated allocation failure for the specific heap. It walks the the heap and sets the nesting level for all allocated cells to zero.

This macro is defined only for debug builds.

See also: RAllocator::__DbgSetAllocFail()

__RHEAP_CHECKFAILURE

Returns the number of heap allocation failures the current debug allocator fail function has caused so far.

This is intended to only be used with fail types RAllocator::EFailNext, RAllocator::EBurstFailNext, RAllocator::EDeterministic and RAllocator::EBurstDeterministic. The return value is unreliable for all other fail types.

See also: RAllocator::TAllocFail

__DEBUGGER

__EMULATOR_IMAGE_HEADER2

__EMULATOR_IMAGE_HEADER

UNICODE

Deprecated

ASSERT

Generates _ASSERT_DEBUG code that calls User::Invariant() if the specified condition is not true.

__DEBUG_ONLY

KIMPORT_C

KEXPORT_C

UIMPORT_C

UEXPORT_C

__ASSERT_COMPILE

Asserts that a condition is true at compilation time.

KSuppressPlatSecDiagnosticMagicValue

const char *constKSuppressPlatSecDiagnosticMagicValue[static]

__PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER

__PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER2

__PLATSEC_DIAGNOSTIC_FILE_AND_LINE

__PLATSEC_DIAGNOSTIC_STRING

A macro that should be used to enclose a platform security diagnostic 'C' style string that can be passed to a capability checking function such as RThread::HasCapability() and Kern::CurrentThreadHasCapability().

The content of the string is emitted if the capability test finds that the capability is not present.

The macro provides a convenient mechanism that allows the strings to be removed from future versions of Symbian OS.

For example:

if(!Kern::CurrentThreadHasCapability(ECapabilityPowerMgmt,__PLATSEC_DIAGNOSTIC_STRING("Checked by Hal function EDisplayHalSetState")))
    {
    return KErrPermissionDenied;
    }			

In this example, the string:

Checked by Hal function EDisplayHalSetState

is emitted if the calling process does not have the ECapabilityPowerMgmt capability.

See also: RProcess::HasCapability() RThread::HasCapability() RMessagePtr2::HasCapability() User::CreatorHasCapability()

KSuppressPlatSecDiagnostic

const char *constKSuppressPlatSecDiagnostic[static]

When this value is used in Platform Security APIs as the value for the aDiagnosticText argument, these APIs will not emit any form of diagnostic message.

__SOFTFP

Calling convention qualifier for functions involving floating point variables passed or returned by value.