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 }
typedef void | TAny |
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 signed char | TInt8 |
8-bit signed integer type, used in Symbian OS to mean an 8-bit signed integer, independent of the implementation.
typedef unsigned char | TUint8 |
8-bit unsigned integer type; used in Symbian OS to mean an 8-bit unsigned integer, independent of the implementation.
typedef short int | TInt16 |
16-bit signed integer type, used in Symbian OS to mean a 16-bit signed integer, independent of the implementation.
typedef unsigned short int | TUint16 |
16-bit unsigned integer type. used in Symbian OS to mean a 16-bit unsigned integer, independent of the implementation.
typedef long int | TInt32 |
32-bit signed integer type, used in Symbian OS to mean a 32-bit signed integer, independent of the implementation.
typedef TInt32 | TIntPtr |
typedef unsigned long int | TUint32 |
32-bit unsigned integer type; used in Symbian OS to mean a 32-bit unsigned integer, independent of the implementation.
typedef TUint32 | TUintPtr |
typedef signed int | TInt |
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.
typedef unsigned int | TUint |
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 float | TReal32 |
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 double | TReal64 |
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 double | TReal |
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 unsigned char | TText8 |
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 unsigned short int | TText16 |
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 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; }
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;
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
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.
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
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.
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 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.
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.
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 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
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
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
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
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
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
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
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()
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()
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()
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
Cancels simulated heap allocation failure for the current thread's heap.
This macro is defined only for debug builds.
See also: User::__DbgSetAllocFail()
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.
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
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
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
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()
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()
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
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
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()
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()
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()
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()
Cancels simulated allocation failure for the specific heap.
This macro is defined only for debug builds.
See also: RAllocator::__DbgSetAllocFail()
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()
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
Generates _ASSERT_DEBUG code that calls User::Invariant() if the specified condition is not true.
const char *const | KSuppressPlatSecDiagnosticMagicValue | [static] |
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()