epoc32/include/e32def.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /*
     2 * Copyright (c) 1994-2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of the License "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:
    15 * e32\include\e32def.h
    16 * NOTE: THIS FILE SHOULD BE ACCEPTABLE TO A C COMPILER
    17 * 
    18 *
    19 */
    20 
    21 
    22 
    23 #ifndef __E32DEF_H__
    24 #define __E32DEF_H__
    25 
    26 /*
    27  * __LEAVE_EQUALS_THROW__ requires the compiler to support C++ exceptions
    28  */
    29 #ifndef __SUPPORT_CPP_EXCEPTIONS__
    30 #undef __LEAVE_EQUALS_THROW__
    31 #endif
    32 
    33 
    34 #if defined(__VC32__)
    35 /**
    36 @publishedAll
    37 @released
    38 */
    39 #define __NO_CLASS_CONSTS__
    40 #if (_MSC_VER >= 1200)
    41 /**
    42 @publishedAll
    43 @released
    44 */
    45 #define __NORETURN__ __declspec(noreturn)
    46 #else
    47 #define __NORETURN__
    48 #endif
    49 /**
    50 @publishedAll
    51 @released
    52 */
    53 #define __NORETURN_TERMINATOR()
    54 /**
    55 @publishedAll
    56 @released
    57 */
    58 #define IMPORT_C __declspec(dllexport)
    59 /**
    60 @publishedAll
    61 @released
    62 */
    63 #define EXPORT_C __declspec(dllexport)
    64 /**
    65 @publishedAll
    66 @released
    67 */
    68 #define IMPORT_D __declspec(dllexport)
    69 /**
    70 @publishedAll
    71 @released
    72 */
    73 #define EXPORT_D __declspec(dllexport)
    74 /**
    75 @publishedAll
    76 @released
    77 */
    78 #define NONSHARABLE_CLASS(x) class x
    79 /**
    80 @publishedAll
    81 @released
    82 */
    83 #define NONSHARABLE_STRUCT(x) struct x
    84 /**
    85 @publishedAll
    86 @released
    87 */
    88 #define __NO_THROW throw()
    89 /**
    90 @publishedAll
    91 @released
    92 */
    93 #define __THROW(t) throw(t)
    94 #pragma warning( disable : 4355 )	/* 'this' used in base member initializer list */
    95 #pragma warning( disable : 4511 )	/* copy constructor could not be generated */
    96 #pragma warning( disable : 4512 )	/* assignment operator could not be generated */
    97 #pragma warning( disable : 4514 )	/* unreferenced inline function has been removed */
    98 #pragma warning( disable : 4699 )	/* Note: Using precompiled header %s */
    99 #pragma warning( disable : 4710 )	/* function not inlined */
   100 #pragma warning( disable : 4121 )	/* alignment sensitive to packing */
   101 #pragma warning( disable : 4273 )
   102 #pragma warning( disable : 4097 )	/* typedef-name 'identifier1' used as synonym for class-name 'identifier2' */
   103 #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 */
   104 
   105 #if _MSC_VER  >= 1100
   106 /**
   107 @publishedAll
   108 @released
   109 */
   110 #define TEMPLATE_SPECIALIZATION template<>
   111 #else
   112 #define TEMPLATE_SPECIALIZATION
   113 #endif
   114 #endif
   115 
   116 
   117 
   118 #if defined(__CW32__)
   119 #undef __embedded_cplusplus
   120 /** @internalTechnology */
   121 #define __embedded_cplusplus	1
   122 #define __NO_CLASS_CONSTS__
   123 #define __NORETURN__
   124 #define __NORETURN_TERMINATOR()
   125 #define IMPORT_C __declspec(dllexport)
   126 #define EXPORT_C __declspec(dllexport)
   127 #define IMPORT_D __declspec(dllexport)
   128 #define EXPORT_D __declspec(dllexport)
   129 #define NONSHARABLE_CLASS(x) class x
   130 #define NONSHARABLE_STRUCT(x) struct x
   131 #define __NO_THROW throw()
   132 #define __THROW(t) throw(t)
   133 
   134 #define TEMPLATE_SPECIALIZATION template<>
   135 /**
   136 @publishedAll
   137 @released
   138 */
   139 #define _asm	asm
   140 #ifndef __int64
   141 #pragma longlong on
   142 /** @internalTechnology */
   143 #define __int64  long long
   144 #endif
   145 #ifndef __SUPPORT_CPP_EXCEPTIONS__
   146 #pragma exceptions off    /* no support for C++ exception handling */
   147 #pragma RTTI off          /* no support for C++ runtime type information */
   148 #endif
   149 #if __MWERKS__ >= 0x3200
   150 #pragma warning off (10480)	/* deleteing void pointer is undefined */
   151 #pragma warning off (10350) /* N pad byte(s) inserted after data member */
   152 #endif
   153 #endif
   154 
   155 
   156 //
   157 // GCC (ARM) compiler
   158 //
   159 #if defined(__GCC32__) && defined(__MARM__)
   160 #ifndef __GNUC__		/* GCC98r2 doesn't define this for some reason */
   161 #define __GNUC__	2
   162 #endif
   163 #define __NO_CLASS_CONSTS__
   164 #define __NORETURN__  __attribute__ ((noreturn))
   165 #ifdef __GCCV3__
   166 #define __NORETURN_TERMINATOR()
   167 #else
   168 #define __NORETURN_TERMINATOR()		abort()
   169 #endif
   170 #define IMPORT_C
   171 #define IMPORT_D
   172 #if !defined __WINS__ && defined _WIN32 /* VC++ Browser Hack */
   173 #define EXPORT_C
   174 #define EXPORT_D
   175 /** @internalTechnology */
   176 #define asm(x)
   177 #else
   178 #define EXPORT_C __declspec(dllexport)
   179 #define EXPORT_D __declspec(dllexport)
   180 #endif
   181 #define NONSHARABLE_CLASS(x) class x
   182 #define NONSHARABLE_STRUCT(x) struct x
   183 #define __NO_THROW
   184 #define __THROW(t)
   185 #ifdef __EABI__
   186 #define TEMPLATE_SPECIALIZATION template<>
   187 #else
   188 #define TEMPLATE_SPECIALIZATION
   189 #endif
   190 /**
   191 @publishedAll
   192 @released
   193 */
   194 #define __DOUBLE_WORDS_SWAPPED__
   195 #endif
   196 
   197 
   198 /** @internalTechnology */
   199 #define __NO_MUTABLE_KEYWORD
   200 #if defined(__NO_MUTABLE_KEYWORD)
   201 /**
   202 @publishedAll
   203 @deprecated
   204 */
   205 #define __MUTABLE
   206 #else
   207 #define __MUTABLE mutable
   208 #endif
   209 
   210 
   211 
   212 /**
   213 @publishedAll
   214 @deprecated
   215 */
   216 #define CONST_CAST(type,exp) (const_cast<type>(exp))
   217 
   218 /**
   219 @publishedAll
   220 @deprecated
   221 */
   222 #define STATIC_CAST(type,exp) (static_cast<type>(exp))
   223 
   224 /**
   225 @publishedAll
   226 @deprecated
   227 */
   228 #define REINTERPRET_CAST(type,exp) (reinterpret_cast<type>(exp))
   229 
   230 #if defined(__NO_MUTABLE_KEYWORD)
   231 /**
   232 @publishedAll
   233 @deprecated
   234 */
   235 #define MUTABLE_CAST(type,exp) (const_cast<type>(exp))
   236 #else
   237 #define MUTABLE_CAST(type,exp) (exp)
   238 #endif
   239 
   240 /**
   241 @publishedAll
   242 @deprecated
   243 */
   244 #define GLREF_D extern
   245 /**
   246 @publishedAll
   247 @deprecated
   248 */
   249 #define GLDEF_D
   250 /**
   251 @publishedAll
   252 @deprecated
   253 */
   254 #define LOCAL_D static
   255 /**
   256 @publishedAll
   257 @deprecated
   258 */
   259 #define GLREF_C extern
   260 /**
   261 @publishedAll
   262 @deprecated
   263 */
   264 #define GLDEF_C
   265 /**
   266 @publishedAll
   267 @deprecated
   268 */
   269 #define LOCAL_C static
   270 /**
   271 @internalAll
   272 @prototype
   273 */
   274 #ifndef IMPORT_D
   275 #define IMPORT_D IMPORT_C 
   276 #endif
   277 
   278 /**
   279 @publishedAll
   280 @deprecated
   281 */
   282 #define FOREVER for(;;)
   283 
   284 
   285 
   286 
   287 /**
   288 @publishedAll
   289 @released
   290 
   291 Symbolic definition for a true value.
   292 */
   293 #define TRUE 1
   294 
   295 
   296 
   297 
   298 /**
   299 @publishedAll
   300 @released
   301 
   302 Symbolic definition for a false value.
   303 */
   304 #define FALSE 0
   305 #ifndef NULL
   306 
   307 
   308 
   309 
   310 /**
   311 @publishedAll
   312 @released
   313 
   314 Symbolic definition for a NULL value.
   315 */
   316 #define NULL 0
   317 #endif
   318 
   319 
   320 
   321 
   322 #ifndef VA_START
   323 /**
   324 @publishedAll
   325 @released
   326 
   327 A macro used by Symbian OS code for handling a variable argument list
   328 in a function call.
   329 
   330 Sets a pointer to point to the first of the variable arguments.
   331 
   332 Typical usage:
   333 
   334 @code
   335 Foo(CAbcdef aAbcdef,...)
   336    {
   337    VA_LIST list;
   338    VA_START(list, aAbcdef);
   339    // other code
   340    } 
   341 @endcode
   342 
   343 @param ap   A pointer used to hold the address of an argument in
   344             the variable argument list. After execution of the code generated 
   345             by this macro, the pointer points to the first argument in
   346             the variable argument list.
   347             This symbol is usually declared as a VA_LIST type. 
   348 
   349 @param pn   The argument that immediately precedes the variable argument list.
   350 
   351 @see VA_LIST
   352 @see VA_ARG
   353 */
   354 #define VA_START(ap,pn) ((ap)[0]=(TInt8 *)&pn+((sizeof(pn)+sizeof(TInt)-1)&~(sizeof(TInt)-1)),(void)0)
   355 #endif
   356 
   357 
   358 
   359 
   360 #ifndef VA_ARG
   361 /**
   362 @publishedAll
   363 @released
   364 
   365 A macro used by Symbian OS code for handling a variable argument list
   366 in a function call.
   367 
   368 Increments a pointer to a variable argument list to point to the next argument
   369 in the list. The current argument is assumed to be of a type defined by
   370 the second parameter to this macro.
   371 
   372 Typical usage:
   373 
   374 @code
   375 Foo(CAbcdef aAbcdef,...)
   376    {
   377    VA_LIST list;
   378    VA_START(list, aAbcdef);
   379    ...
   380    TInt x = VA_ARG(list,TInt);
   381    ...
   382    const TDesC *pS=VA_ARG(aList,const TDesC*);
   383    ... 
   384    etc
   385    } 
   386 @endcode
   387 
   388 @param ap   A pointer used to hold the address of an argument in
   389             the variable argument list. It is assumed to point to the current
   390             argument in the variable argument list. After execution of the code
   391             generated by this macro, the pointer points to the next argument in
   392             the list. This symbol is usually declared as a VA_LIST type. 
   393 
   394 @param type The type of the current argument.
   395             This can be any valid type, for example, TInt, const TDesC*, etc.
   396             
   397 @see VA_LIST
   398 @see VA_START            
   399 */
   400 #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)))))
   401 #endif
   402 
   403 
   404 
   405 
   406 #ifndef VA_END
   407 /**
   408 @publishedAll
   409 @released
   410 
   411 A macro used by Symbian OS code for handling a variable argument list
   412 in a function call.
   413 
   414 Sets a pointer to zero.
   415 
   416 @param ap   A pointer used to hold the address of an argument in
   417             the variable argument list. After execution of the code generated 
   418             by this macro, the pointer is reset to 0.
   419             This symbol is usually declared as a VA_LIST type. 
   420             
   421 @see VA_LIST
   422 @see VA_START
   423 @see VA_ARG            
   424 */
   425 #define VA_END(ap) ((ap)[0]=0,(void)0)
   426 #endif
   427 	
   428 
   429 
   430 /**
   431 @publishedAll
   432 @released
   433 
   434 Calculates the offset of member f within class c.
   435 
   436 This is used in the TSglQue and TDblQue constructors to set the offset of
   437 the link object from the start of a list element.
   438 
   439 @param c The name of the class.
   440 @param f The name of the member within the specified class.
   441 
   442 @see TSglQue
   443 @see TDblQue
   444 */
   445 #ifndef _FOFF
   446 #if __GNUC__ < 4
   447 #define _FOFF(c,f)			(((TInt)&(((c *)0x1000)->f))-0x1000)
   448 #else
   449 #define _FOFF(c,f)			(__builtin_offsetof(c,f))
   450 #endif
   451 #endif
   452 
   453 
   454 
   455 /**
   456 @internalTechnology
   457 @released
   458 */
   459 #define _ALIGN_DOWN(x,a)	((x)&~((a)-1))
   460 /**
   461 @internalTechnology
   462 @released
   463 */
   464 #define _ALIGN_UP(x,a)		_ALIGN_DOWN((x)+(a)-1, a)
   465 
   466 
   467 
   468 
   469 /** 
   470 @publishedAll
   471 @released
   472 
   473 Pointer to any type.
   474 
   475 TAny* is equivalent to void* in standard C or C++. TAny* is used in preference 
   476 to void* because it is more suggestive of the actual meaning,
   477 e.g. TAny* foo();.
   478 
   479 TAny is not used where it really means "nothing", as in the declaration of 
   480 functions which do not return a value; void is used instead, e.g. void Foo();.
   481 */
   482 typedef void TAny;
   483 
   484 
   485 
   486 
   487 /**
   488 @publishedAll
   489 @released
   490 
   491 8-bit signed integer type, used in Symbian OS to mean an 8-bit
   492 signed integer, independent of the implementation.
   493 */
   494 typedef signed char TInt8;
   495 
   496 
   497 
   498 
   499 /**
   500 @publishedAll
   501 @released
   502 
   503 8-bit unsigned integer type; used in Symbian OS to mean an 8-bit
   504 unsigned integer, independent of the implementation.
   505 */
   506 typedef unsigned char TUint8;
   507 
   508 
   509 
   510 
   511 /**
   512 @publishedAll
   513 @released
   514 
   515 16-bit signed integer type, used in Symbian OS to mean a 16-bit
   516 signed integer, independent of the implementation.
   517 */
   518 typedef short int TInt16;
   519 
   520 
   521 
   522 
   523 /**
   524 @publishedAll
   525 @released
   526 
   527 16-bit unsigned integer type. used in Symbian OS to mean a 16-bit
   528 unsigned integer, independent of the implementation.
   529 */
   530 typedef unsigned short int TUint16;
   531 
   532 
   533 
   534 
   535 /**
   536 @publishedAll
   537 @released
   538 
   539 32-bit signed integer type, used in Symbian OS to mean a 32-bit
   540 signed integer, independent of the implementation.
   541 */
   542 typedef long int TInt32;
   543 
   544 
   545 
   546 
   547 /**
   548 @publishedAll
   549 @released
   550 
   551 A signed integer type of the same size as a pointer.
   552 */
   553 typedef TInt32 T_IntPtr;
   554 typedef TInt32 TIntPtr;
   555 
   556 
   557 
   558 
   559 /**
   560 @publishedAll
   561 @released
   562 
   563 32-bit unsigned integer type; used in Symbian OS to mean a 32-bit
   564 unsigned integer, independent of the implementation.
   565 */
   566 typedef unsigned long int TUint32;
   567 
   568 
   569 
   570 
   571 /**
   572 @publishedAll
   573 @released
   574 
   575 An unsigned integer type of the same size as a pointer.
   576 */
   577 typedef TUint32 T_UintPtr;
   578 typedef TUint32 TUintPtr;
   579 
   580 
   581 
   582 
   583 /**
   584 @publishedAll
   585 @released
   586 
   587 Signed integer type of the natural machine word length.
   588 
   589 This is as defined by the C++ implementation's int type. In all
   590 implementations, this is guaranteed to be at least 32 bits.
   591 
   592 A TInt should be used in preference to a sized integer (TInt32, TInt16) for 
   593 all general use. Sized integers should only be used when packing is essential. 
   594 C++'s type conversion rules imply that all sized integers smaller than the 
   595 natural machine word are in any case broadened to the natural machine word 
   596 size when passed as function parameters.
   597 
   598 A TInt should be used in preference to an unsigned integer (TUint) for all 
   599 general use. Unsigned integers should only be used for flags (which use Boolean 
   600 operations but not arithmetic) and, in very rare cases, for numbers whose 
   601 range exceeds that available from signed integers. Although it is natural 
   602 to attempt to use unsigned integers for quantities which cannot by nature 
   603 be negative, the C++ language does not provide the support necessary to enforce 
   604 the "expected" behaviour in these circumstances, and experience has shown 
   605 that it is better to use signed integers unless there is good reason not to.
   606 
   607 @see TUint
   608 @see TInt32
   609 @see TInt16
   610 */
   611 typedef signed int TInt;
   612 
   613 
   614 
   615 
   616 /**
   617 @publishedAll
   618 @released
   619 
   620 Unsigned integer type of the natural machine word length. 
   621 
   622 This is guaranteed to be at least 32 bits in all implementations.
   623 
   624 In almost all circumstances, a TInt should be used in preference to a TUint. 
   625 The main exception is in flags bytes.
   626 
   627 @see TInt
   628 */
   629 typedef unsigned int TUint;
   630 
   631 
   632 
   633 
   634 /**
   635 @publishedAll
   636 @released
   637 
   638 32-bit floating point number, providing IEEE754 single precision on all Symbian 
   639 OS implementations.
   640 
   641 TReal should normally be used in preference to TReal32.
   642 
   643 Use of floating-point numbers should generally be avoided unless a natural 
   644 part of the problem specification. Most Symbian OS implementations do not 
   645 have a hardware floating point unit: as a result, their floating-point performance 
   646 is hundreds of times slower than integer performance.
   647 */
   648 typedef float TReal32;
   649 
   650 
   651 
   652 
   653 /**
   654 @publishedAll
   655 @released
   656 
   657 64-bit floating point number, providing IEEE754 double precision on all Symbian 
   658 OS implementations.
   659 
   660 Use of floating-point numbers should generally be avoided unless a natural 
   661 part of the problem specification. Most Symbian OS implementations do not 
   662 have a hardware floating point unit: as a result, their floating-point performance 
   663 is hundreds of times slower than integer performance.
   664 
   665 This type is identical to TReal.
   666 
   667 @see TReal
   668 */
   669 typedef double TReal64;
   670 
   671 
   672 
   673 
   674 /**
   675 @publishedAll
   676 @released
   677 
   678 64-bit floating point number; identical to TReal64.
   679 
   680 Use of floating-point numbers should generally be avoided unless a natural 
   681 part of the problem specification. Most Symbian OS implementations do not 
   682 have a hardware floating point unit: as a result, their floating-point performance 
   683 is hundreds of times slower than integer performance.
   684 
   685 Most serious floating-point calculations require double-precision. All standard 
   686 math functions (see Math class) take double-precision arguments. Single-precision 
   687 should only be used where space and performance are at a premium, and when 
   688 their limited precision is acceptable.
   689 
   690 @see TReal64
   691 @see Math
   692 */
   693 typedef double TReal;
   694 
   695 
   696 
   697 
   698 /**
   699 @publishedAll
   700 @released
   701 
   702 8-bit unsigned character.
   703 
   704 Use instead of C++ built-in char type because it is guaranteed to be unsigned. 
   705 Use instead of TInt8 where the application is really for text rather than 
   706 8-bit arithmetic or binary quantities.
   707 
   708 For most purposes, you should use TText rather than TText8. TText is mapped 
   709 onto either TText8 or TText16 depending on whether a non-Unicode or Unicode 
   710 variant is being built. Use TText8 only when you are dealing explicitly with 
   711 8-bit text, regardless of build.
   712 
   713 @see TText */
   714 typedef unsigned char TText8;
   715 
   716 
   717 
   718 
   719 /**
   720 @publishedAll
   721 @released
   722 
   723 16-bit unsigned character.
   724 
   725 Use instead of C++ wchar_t type because it is guaranteed to be unsigned. Use 
   726 instead of TInt16 where the application is really for text rather than 8-bit 
   727 arithmetic or binary quantities.
   728 
   729 For most purposes, you should use TText rather than TText16. TText is mapped 
   730 onto either TText8 or TText16 depending on whether a non-Unicode or Unicode 
   731 variant is being built. Use TText16 only when you are dealing explicitly with 
   732 16-bit text, regardless of build.
   733 
   734 @see TText
   735 */
   736 typedef unsigned short int TText16;
   737 
   738 
   739 
   740 
   741 /**
   742 @publishedAll
   743 @released
   744 
   745 Boolean type which takes the value either ETrue or EFalse.
   746 
   747 Although only a single bit would theoretically be necessary to represent a 
   748 Boolean, a machine word is used instead, so that these quantities can be easily 
   749 passed. Also, TBool must map onto int because of C++'s interpretation of 
   750 operands in conditional expressions.
   751 */
   752 typedef int TBool;
   753 
   754 
   755 
   756 
   757 /**
   758 @publishedPartner
   759 @released
   760 
   761 Defines a linear (virtual) address type.
   762 */
   763 typedef T_UintPtr TLinAddr;
   764 
   765 
   766 
   767 #if defined(__GCC32__)
   768 
   769 
   770 
   771 
   772 /**
   773 @publishedAll
   774 @released
   775 
   776 Defines a 64-bit signed integer type.
   777 */
   778 typedef long long Int64;
   779 
   780 
   781 
   782 
   783 /**
   784 @publishedAll
   785 @released
   786 
   787 Defines a 64-bit unsigned integer type.
   788 */
   789 typedef unsigned long long Uint64;
   790 
   791 
   792 
   793 
   794 /**
   795 @publishedAll
   796 @released
   797 */
   798 #define	I64LIT(x)	x##LL
   799 /**
   800 @publishedAll
   801 @released
   802 */
   803 #define	UI64LIT(x)	x##ULL
   804 
   805 #elif defined(__VC32__)
   806 typedef __int64 Int64;
   807 typedef unsigned __int64 Uint64;
   808 #define	I64LIT(x)	(__int64)##x
   809 #define	UI64LIT(x)	(unsigned __int64)##x
   810 
   811 #elif defined(__CW32__)
   812 #pragma longlong on
   813 typedef long long Int64;
   814 typedef unsigned long long Uint64;
   815 #define	I64LIT(x)	x##LL
   816 #define	UI64LIT(x)	x##ULL
   817 #endif
   818 
   819 
   820 
   821 
   822 /**
   823 @publishedAll
   824 @released
   825 
   826 Defines a 64-bit signed integer type.
   827 
   828 NOTE: For those migrating from versions of Symbian OS before 8.1b (i.e. 8.1a, 7.0s etc)
   829 TInt64 is now defined as a built-in type instead of as a class type. This means
   830 that the member functions of the old TInt64 class are no longer exported
   831 from EUSER.LIB, and represents a compatibility break.
   832 
   833 To ease migration of source code, a number of macros are provided. Similar
   834 macros have also been defined in Symbian OS versions 7.0s and 8.1a, but
   835 implemented in terms of the old TInt64 class. This is important for code that
   836 is common to : one or both of these Symbian OS versions, and to 8.1b and
   837 subsequent versions.
   838 
   839 The following list shows the new macros and the functions that they replace.
   840 It also shows some alternative techniques.
   841 In this list: x, v and r are declared as TInt64, c is declared as TInt, High
   842 and Low are declared as TUint.
   843 
   844 @code
   845 OLD USAGE						REPLACEMENT
   846 
   847 TInt64(High,Low);				MAKE_TINT64(High,Low);
   848 x.Set(High,Low);				MAKE_TINT64(High,Low);
   849 x.Low();						I64LOW(x);
   850 x.High();						I64HIGH(x); 
   851 x.GetTInt();					I64INT(x); 
   852 x.GetTReal();					I64REAL(x); 
   853 x.Lsr(c);						I64LSR(x,c); 
   854 x.Mul10();						x*=10; 
   855 x.MulTop(a);					I64MULTOP(x,a); 
   856 x.DivMod(v,r);					r=x%v; x/=v;
   857 @endcode 
   858 */
   859 typedef	Int64	TInt64;
   860 
   861 
   862 
   863 
   864 /**
   865 @publishedAll
   866 @released
   867  
   868 Defines a 64-bit unsigned integer type.
   869 */
   870 typedef	Uint64	TUint64;
   871 
   872 
   873 
   874 
   875 /** @internalComponent */
   876 #define _MAKE_TINT64_ZX(x)	((TInt64)((TUint32)(x)))
   877 
   878 /** @internalComponent */
   879 #define _MAKE_TUINT64_ZX(x)	((TUint64)((TUint32)(x)))
   880 
   881 
   882 
   883 
   884 /**
   885 @publishedAll
   886 @released
   887 */
   888 #define MAKE_TINT64(h,l)	( (_MAKE_TINT64_ZX(h)<<32) | _MAKE_TINT64_ZX(l) )
   889 
   890 
   891 
   892 
   893 /**
   894 @publishedAll
   895 @released
   896 */
   897 #define MAKE_TUINT64(h,l)	( (_MAKE_TUINT64_ZX(h)<<32) | _MAKE_TUINT64_ZX(l) )
   898 
   899 
   900 
   901 
   902 /**
   903 @publishedAll
   904 @released
   905 
   906 Generates code to access the high order 32 bits of a 64 bit number.
   907 */
   908 #define	I64HIGH(x)			( (TUint32)((x)>>32) )
   909 
   910 
   911 
   912 
   913 /**
   914 @publishedAll
   915 @released
   916 
   917 Generates code to access the low order 32 bits of a 64 bit number.
   918 */
   919 #define	I64LOW(x)			( (TUint32)(x) )
   920 
   921 
   922 
   923 
   924 /**
   925 @publishedAll
   926 @released
   927 
   928 Generates code to cast a 64 bit value as an signed integer.
   929 */
   930 #define	I64INT(x)			( (TInt)(x) )
   931 
   932 
   933 
   934 
   935 /**
   936 @publishedAll
   937 @released
   938 
   939 Generates code to cast a 64 bit value as a TReal type.
   940 */
   941 #define	I64REAL(x)			( (TReal)(x) )
   942 
   943 
   944 
   945 
   946 /**
   947 @publishedAll
   948 @released
   949 
   950 Generates code to logically shift a 64 bit integer right.
   951 */
   952 #define	I64LSR(x, shift)	( *reinterpret_cast<TUint64*>(&(x)) >>= (shift) )
   953 
   954 
   955 
   956 /**
   957 @publishedAll
   958 @released
   959 
   960 Generates code to multiply a 64 bit integer by 10.
   961 */
   962 #define	I64MUL10(x)			( (x) *= 10 )
   963 
   964 
   965 
   966 /**
   967 @publishedAll
   968 @released
   969 
   970 Generates code to divide a 64 bit integer by another and find the remainder.
   971 */
   972 #define	I64DIVMOD(x, divisor, remainder)	( ((remainder) = (x) % (divisor), (x) /= (divisor)) )
   973 
   974 
   975 
   976 
   977 /**
   978 @publishedAll
   979 @released
   980 
   981 Generates code to cast a double to a 64 bit integer.
   982 */
   983 #define	I64DOUBLECAST(x)	( static_cast<TInt64>(x) )
   984 
   985 
   986 
   987 
   988 /**
   989 @publishedAll
   990 @deprecated Use _LIT8 instead.
   991 
   992 8-bit literal.
   993 
   994 The macro defines an explicit 8-bit constant literal which is suitable
   995 for non-Unicode literal text, regardless of the build.
   996 
   997 @see _L
   998 @see _LIT8
   999 @see _LIT
  1000 */
  1001 #define _L8(a) (TPtrC8((const TText8 *)(a)))
  1002 
  1003 
  1004 
  1005 
  1006 /**
  1007 @publishedAll
  1008 @released
  1009 
  1010 Defines an explicit 8-bit string which is suitable when non-Unicode text
  1011 is required, regardless of the build.
  1012 
  1013 This is used by the deprecated literal descriptor _L8.
  1014 */
  1015 #define _S8(a) ((const TText8 *)a)
  1016 
  1017 
  1018 
  1019 
  1020 /**
  1021 @publishedAll
  1022 @released
  1023 
  1024 Constructs a constant literal descriptor of type TLitC8<TInt> with
  1025 the specified name and text.
  1026 
  1027 The 8-bit build variant is generated for both non-Unicode and Unicode builds.
  1028 
  1029 @param name The name of the C++ variable to be generated.
  1030 @param s    The literal text enclosed within a pair of double quotes. 
  1031 
  1032 @see _LIT
  1033 */
  1034 #define _LIT8(name,s) const static TLitC8<sizeof(s)> name={sizeof(s)-1,s}
  1035 
  1036 
  1037 
  1038 
  1039 /**
  1040 @publishedAll
  1041 @deprecated Use _LIT16 instead.
  1042 
  1043 16-bit literal.
  1044 
  1045 The macro defines an explicit 16-bit constant literal which is suitable
  1046 for Unicode literal text, regardless of the build.
  1047 
  1048 @see _L
  1049 @see _LIT16
  1050 @see _LIT
  1051 */
  1052 #define _L16(a) (TPtrC16((const TText16 *)L ## a))
  1053 
  1054 
  1055 
  1056 /**
  1057 @publishedAll
  1058 @released
  1059 
  1060 Defines an explicit 16-bit string which is suitable when Unicode text
  1061 is required, regardless of the build.
  1062 
  1063 This is used by the deprecated literal descriptor _L16.
  1064 */
  1065 #define _S16(a) ((const TText16 *)L ## a)
  1066 
  1067 
  1068 
  1069 
  1070 /**
  1071 @publishedAll
  1072 @released
  1073 
  1074 Constructs a constant literal descriptor of type TLitC16<TInt> with
  1075 the specified name and text.
  1076 
  1077 The 16-bit build variant is generated for both non-Unicode and Unicode builds.
  1078 
  1079 @param name The name of the C++ variable to be generated.
  1080 @param s    The literal text enclosed within a pair of double quotes. 
  1081 
  1082 @see _LIT
  1083 */
  1084 #define _LIT16(name,s) const static TLitC16<sizeof(L##s)/2> name={sizeof(L##s)/2-1,L##s}
  1085 
  1086 
  1087 
  1088 
  1089 #if defined(_UNICODE) && !defined(__KERNEL_MODE__)
  1090 /**
  1091 @publishedAll
  1092 @released
  1093 
  1094 Build independent general text character.
  1095 
  1096 In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is 
  1097 mapped to TText16. Use the classes with explicit width only when you wish 
  1098 the width to be independent of the build variant.
  1099 
  1100 Use this class rather than TChar for general use.
  1101 */
  1102 typedef TText16 TText;
  1103 
  1104 
  1105 
  1106 /**
  1107 @publishedAll
  1108 @deprecated Use _LIT instead.
  1109 
  1110 Build independent literal. 
  1111 
  1112 The macro defines either an 8-bit constant literal (for non-Unicode text),
  1113 or a 16-bit constant literal (for Unicode text) depending on the build.
  1114 
  1115 @see _LIT
  1116 @see _L16
  1117 @see _L8
  1118 */
  1119 #define _L(a) (TPtrC((const TText *)L ## a))
  1120 
  1121 
  1122 
  1123 
  1124 /**
  1125 @publishedAll
  1126 @released
  1127 
  1128 Defines either an 8-bit string (for non-Unicode text),
  1129 or a 16-bit string (for Unicode text) depending on the build.
  1130 
  1131 This is used by the deprecated build independent literal _L.
  1132 */
  1133 #define _S(a) ((const TText *)L ## a)
  1134 
  1135 
  1136 
  1137 
  1138 /**
  1139 @publishedAll
  1140 @released
  1141 
  1142 Constructs a build independent constant literal descriptor of type TLitC<TInt>
  1143 with the specified name and text.
  1144 
  1145 An 8-bit build variant is generated for a non-Unicode build;
  1146 A 16-bit build variant is generated for a Unicode build.
  1147 
  1148 @param name The name of the C++ variable to be generated.
  1149 @param s    The literal text enclosed within a pair of double quotes. 
  1150 
  1151 @see _LIT16
  1152 @see _LIT8
  1153 */
  1154 #define _LIT(name,s) const static TLitC<sizeof(L##s)/2> name={sizeof(L##s)/2-1,L##s}
  1155 
  1156 
  1157 
  1158 
  1159 #else
  1160 /**
  1161 @publishedAll
  1162 @released
  1163 
  1164 Build independent general text character.
  1165 
  1166 In non-Unicode builds, this is mapped to TText8. In Unicode builds, this is 
  1167 mapped to TText16. Use the classes with explicit width only when you wish 
  1168 the width to be independent of the build variant.
  1169 
  1170 Use this class rather than TChar for general use.
  1171 */
  1172 typedef TText8 TText;
  1173 
  1174 
  1175 
  1176 /**
  1177 @publishedAll
  1178 @released
  1179 
  1180 @deprecated Use _LIT instead.
  1181 
  1182 Build independent literal. 
  1183 
  1184 The macro defines either an 8-bit constant literal (for non-Unicode text),
  1185 or a 16-bit constant literal (for Unicode text) depending on the build.
  1186 
  1187 @see _LIT
  1188 @see _L16
  1189 @see _L8
  1190 */
  1191 #define _L(a) (TPtrC((const TText *)(a)))
  1192 
  1193 
  1194 
  1195 
  1196 /**
  1197 @publishedAll
  1198 @released
  1199 
  1200 Defines either an 8-bit string (for non-Unicode text),
  1201 or a 16-bit string (for Unicode text) depending on the build.
  1202 
  1203 This is used by the deprecated build independent literal _L.
  1204 */
  1205 #define _S(a) ((const TText *)a)
  1206 
  1207 
  1208 
  1209 
  1210 /**
  1211 @publishedAll
  1212 @released
  1213 
  1214 Constructs a build independent constant literal descriptor of type TLitC<TInt>
  1215 with the specified name and text.
  1216 
  1217 An 8-bit build variant is generated for a non-Unicode build;
  1218 A 16-bit build variant is generated for a Unicode build.
  1219 
  1220 @param name The name of the C++ variable to be generated.
  1221 @param s    The literal text enclosed within a pair of double quotes. 
  1222 
  1223 @see _LIT16
  1224 @see _LIT8
  1225 */
  1226 #define _LIT(name,s) const static TLitC<sizeof(s)> name={sizeof(s)-1,s}
  1227 #endif
  1228 
  1229 
  1230 
  1231 
  1232 #ifndef __VA_LIST_defined
  1233 /** 
  1234 @publishedAll
  1235 @released
  1236 
  1237 Defines a 'C' style array of pointers to TInt8 types.
  1238 
  1239 The type is most commonly used by code that needs to deal with a variable
  1240 number of arguments passed to a function.
  1241 
  1242 @see TInt8
  1243 */
  1244 typedef TInt8 *VA_LIST[1];
  1245 #endif
  1246 
  1247 /** 
  1248 @publishedAll
  1249 @released
  1250 
  1251 Asserts that a condition is true.
  1252 
  1253 Code is generated for all builds.
  1254 
  1255 This macro is used as a C++ statement to assert the truth of some condition,
  1256 and to take appropriate action if the condition is false. Unlike __ASSERT_DEBUG
  1257 it is defined in both release and debug builds.
  1258 
  1259 The most common use for this macro is to check that the external environment of
  1260 a function or class is behaving as expected; for example, that parameters
  1261 passed to a function are credible, or that called functions are behaving as
  1262 expected; the macro is commonly placed at the beginning of a function.
  1263 
  1264 The effect of the macro is to generate code which tests
  1265 the conditional expression c; if the expression is false, then
  1266 function p is called. In the majority of cases, the function p is one that
  1267 raises a panic.
  1268 
  1269 Note that the macro definition is, in effect, equivalent to: 
  1270 
  1271 @code
  1272 if !(c)p;
  1273 @endcode
  1274 
  1275 @param c a conditional expression which results in true or false.
  1276 @param p a function which is called if the conditional expression c is false.
  1277 
  1278 @see __ASSERT_DEBUG
  1279 */
  1280 #define __ASSERT_ALWAYS(c,p) (void)((c)||(p,0))
  1281 
  1282 
  1283 
  1284 #ifdef __WINS__
  1285 #ifdef __CW32__
  1286 /** 
  1287 @internalAll
  1288 @released
  1289 */
  1290 #define __BREAKPOINT()			\
  1291 	{							\
  1292 	__asm { byte 0xcc };		\
  1293 	}
  1294 #else // !__CW32__
  1295 /** 
  1296 @internalAll
  1297 @released
  1298 */
  1299 #define __BREAKPOINT()			\
  1300 	{							\
  1301 	__asm { int 3 };			\
  1302 	}
  1303 #endif //__CW32__
  1304 #else
  1305 /** 
  1306 @internalAll
  1307 @released
  1308 */
  1309 #define __BREAKPOINT()
  1310 #endif
  1311 
  1312 #if defined(_DEBUG)
  1313 
  1314 
  1315 /** 
  1316 @publishedAll
  1317 @released
  1318 
  1319 Asserts that a condition is true.
  1320 
  1321 Code is generated for debug builds only.
  1322 
  1323 This macro is used as a C++ statement to assert the truth of some condition,
  1324 and to take appropriate action if the condition is false. It is used in
  1325 the same way as __ASSERT_ALWAYS, except that it is only defined for debug builds.
  1326 
  1327 The macro may be used to insert extra checks at various points in source code
  1328 as desired; the code will only be generated in debug builds and not in release
  1329 builds.
  1330 
  1331 @param c A conditional expression which results in true or false.
  1332 @param p A function which is called if the conditional expression c is false.
  1333 
  1334 @see __ASSERT_ALWAYS
  1335 */
  1336 #define __ASSERT_DEBUG(c,p) (void)((c)||(p,0))
  1337 
  1338 
  1339 
  1340 /** 
  1341 @internalAll
  1342 @removed
  1343 */
  1344 #define __DECLARE_NAME(t)
  1345 
  1346 
  1347 
  1348 
  1349 /** 
  1350 @publishedAll
  1351 @released
  1352 
  1353 Calls the function for testing object invariance.
  1354 
  1355 Classes can define a standard member function __DbgTestInvariant(),
  1356 which checks that the object is in a valid state, and panics if it is not.
  1357 In debug builds, this macro simply expands to call that function. For details on how
  1358 to define __DbgTestInvariant(), and an example of its use, see __DECLARE_TEST.
  1359 
  1360 The macro is typically invoked at the beginning of all the member functions of
  1361 the class. For non-const functions (those which can change the object’s state),
  1362 you can ensure that the object has been left in a stable state by invoking
  1363 the macro at the end of the function.
  1364 
  1365 In release builds, no code is generated for the macro. 
  1366 */
  1367 #define __TEST_INVARIANT __DbgTestInvariant()
  1368 
  1369 
  1370 
  1371 
  1372 /**
  1373 @publishedAll
  1374 @released
  1375 
  1376 Marks the start of checking the current thread's heap. 
  1377 
  1378 This macro is defined only for debug builds.
  1379 
  1380 This macro must be matched by a corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
  1381 
  1382 Calls to this macro can be nested but each call must be matched by corresponding 
  1383 call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
  1384 
  1385 @see User::__DbgMarkStart()
  1386 @see __UHEAP_MARKEND
  1387 @see __UHEAP_MARKENDC
  1388 */
  1389 #define __UHEAP_MARK User::__DbgMarkStart(FALSE)
  1390 
  1391 
  1392 
  1393 
  1394 /**
  1395 @publishedAll
  1396 @released
  1397 
  1398 Checks that the number of allocated cells at the current nested level on the 
  1399 current thread's heap is the same as the specified value.
  1400 
  1401 This macro is defined only for debug builds.
  1402 
  1403 The macro also takes the name of the file containing this source code statement 
  1404 and the line number of this source code statement; they are displayed as part 
  1405 of the panic category, if the checks fail.
  1406 
  1407 The macro assumes that:
  1408 
  1409 1. the heap being checked is a user heap
  1410 
  1411 2. checking is being done for the number of allocated cells at the current nested 
  1412    level; i.e. that aCountAll is set to false
  1413 
  1414 3. the line number is the line number of this source code statement.
  1415 
  1416 4. the file name is the full path name of the file containing this source statement
  1417 
  1418 @param aCount The number of heap cells expected to be allocated at
  1419               the current nest level.
  1420 
  1421 @see User::__DbgMarkCheck()
  1422 @see __KHEAP_CHECK
  1423 */
  1424 #define __UHEAP_CHECK(aCount) User::__DbgMarkCheck(FALSE,FALSE,aCount,(TText8*)__FILE__,__LINE__)
  1425 
  1426 
  1427 
  1428 
  1429 /**
  1430 @publishedAll
  1431 @released
  1432 
  1433 Checks that the total number of allocated cells on the current thread's heap 
  1434 is the same as the specified value.
  1435 
  1436 This macro is defined only for debug builds.
  1437 
  1438 The macro also takes the name of the file containing this source code statement 
  1439 and the line number of this source code statement; they are displayed as part 
  1440 of the panic category, if the checks fail.
  1441 
  1442 @param aCount The total number of heap cells expected to be allocated.
  1443 
  1444 @see User::__DbgMarkCheck()
  1445 @see __KHEAP_CHECKALL
  1446 */
  1447 #define __UHEAP_CHECKALL(aCount) User::__DbgMarkCheck(FALSE,TRUE,aCount,(TText8*)__FILE__,__LINE__)
  1448 
  1449 
  1450 
  1451 
  1452 /**
  1453 @publishedAll
  1454 @released
  1455 
  1456 Marks the end of checking the current thread's heap. 
  1457 
  1458 The macro expects zero heap cells to remain allocated at the current nest 
  1459 level. This macro is defined only for debug builds.
  1460 
  1461 This macro must match an earlier call to __UHEAP_MARK.
  1462 
  1463 @see User::__DbgMarkEnd()
  1464 @see __UHEAP_MARK
  1465 */
  1466 #define __UHEAP_MARKEND User::__DbgMarkEnd(FALSE,0)
  1467 
  1468 
  1469 
  1470 
  1471 /**
  1472 @publishedAll
  1473 @released
  1474 
  1475 Marks the end of checking the current thread's heap. 
  1476 
  1477 The macro expects aCount heap cells to remain allocated at the current nest 
  1478 level.
  1479 
  1480 This macro must match an earlier call to __UHEAP_MARK.
  1481 
  1482 @param aCount The number of heap cells expected to remain allocated at
  1483               the current nest level.
  1484 
  1485 @see User::__DbgMarkEnd()
  1486 @see __UHEAP_MARK
  1487 */
  1488 #define __UHEAP_MARKENDC(aCount) User::__DbgMarkEnd(FALSE,aCount)
  1489 
  1490 
  1491 
  1492 
  1493 /**
  1494 @publishedAll
  1495 @released
  1496 
  1497 Simulates heap allocation failure for the current thread's heap.
  1498 
  1499 The failure occurs on the next call to new or any of the functions which 
  1500 allocate memory from the heap. This macro is defined only for debug builds.
  1501 
  1502 @param aCount Determines when the allocation will fail.
  1503               Heap allocation fails on attempt number aCount - later
  1504               allocations will succeed.
  1505               For example, if aCount is 3, then heap allocation fails
  1506               on the 3rd attempt, but all subsequent allocations succeed. 
  1507 
  1508 @see User::__DbgSetAllocFail()
  1509 */
  1510 #define __UHEAP_FAILNEXT(aCount) User::__DbgSetAllocFail(FALSE,RAllocator::EFailNext,aCount)
  1511 
  1512 /**
  1513 @publishedAll
  1514 @released
  1515 
  1516 Simulates heap allocation failure for the current thread's heap.
  1517 
  1518 The failures will occur for aBurst times from the next call to new or any of the functions which 
  1519 allocate memory from the heap. This macro is defined only for debug builds.
  1520 
  1521 @param aCount Determines when the allocation will fail.
  1522               Heap allocation fails on attempt number aCount - later
  1523               allocations will succeed.
  1524               For example, if aCount is 3, then heap allocation fails
  1525               on the 3rd attempt, but all subsequent allocations succeed.  
  1526               Note when used with RHeap the maximum value aCount can be set 
  1527               to is KMaxTUint16.
  1528 @param aBurst The number of consecutive allocations that will fail.  Note 
  1529               when used with RHeap the maximum value aBurst can be set to 
  1530               is KMaxTUint16.
  1531 
  1532 @see User::__DbgSetBurstAllocFail()
  1533 */
  1534 #define __UHEAP_BURSTFAILNEXT(aCount,aBurst) User::__DbgSetBurstAllocFail(FALSE,RAllocator::EBurstFailNext,aCount,aBurst)
  1535 
  1536 
  1537 
  1538 /**
  1539 @publishedAll
  1540 @released
  1541 
  1542 Simulates heap allocation failure for the current thread's heap. 
  1543 
  1544 The failure occurs on subsequent calls to new or any of the functions which 
  1545 allocate memory from the heap. This macro is defined only for debug builds.
  1546 
  1547 @param aType  The type of failure to be simulated.
  1548 @param aRate The failure rate.
  1549 
  1550 @see User::__DbgSetAllocFail()
  1551 @see RAllocator::TAllocFail
  1552 */
  1553 #define __UHEAP_SETFAIL(aType,aRate) User::__DbgSetAllocFail(FALSE, aType, aRate)
  1554 
  1555 /**
  1556 @publishedAll
  1557 @released
  1558 
  1559 Simulates heap allocation failure for the current thread's heap. 
  1560 
  1561 The failure occurs on subsequent calls to new or any of the functions which 
  1562 allocate memory from the heap. This macro is defined only for debug builds.
  1563 
  1564 @param aType  The type of failure to be simulated.
  1565 @param aRate  The failure rate.  Note when used with RHeap the maximum value 
  1566               aRate can be set to is KMaxTUint16.
  1567 @param aBurst The number of consecutive allocations that will fail.    Note 
  1568               when used with RHeap the maximum value aBurst can be set 
  1569               to is KMaxTUint16.
  1570 
  1571 @see User::__DbgSetBurstAllocFail()
  1572 @see RAllocator::TAllocFail
  1573 */
  1574 #define __UHEAP_SETBURSTFAIL(aType,aRate,aBurst) User::__DbgSetBurstAllocFail(FALSE, aType, aRate, aBurst)
  1575 
  1576 
  1577 
  1578 /**
  1579 @publishedAll
  1580 @released
  1581 
  1582 Cancels simulated heap allocation failure for the current thread's heap. 
  1583 
  1584 This macro is defined only for debug builds.
  1585 
  1586 @see User::__DbgSetAllocFail()
  1587 */
  1588 #define __UHEAP_RESET User::__DbgSetAllocFail(FALSE,RAllocator::ENone,1)
  1589 
  1590 
  1591 /**
  1592 @publishedAll
  1593 @released
  1594 
  1595 Cancels simulated heap allocation failure for the current thread's heap. 
  1596 It walks the the heap and sets the nesting level for all allocated
  1597 cells to zero.
  1598 
  1599 This macro is defined only for debug builds.
  1600 */
  1601 #define __UHEAP_TOTAL_RESET User::__DbgSetAllocFail(FALSE,RAllocator::EReset,1)
  1602 
  1603 /**
  1604 @publishedAll
  1605 @released
  1606 
  1607 Returns the number of heap allocation failures the current debug allocator fail
  1608 function has caused so far.
  1609 
  1610 This is intended to only be used with fail types RAllocator::EFailNext,
  1611 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  1612 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  1613 all other fail types.
  1614 
  1615 @return The number of heap allocation failures the current debug fail 
  1616 function has caused.
  1617 
  1618 @see RAllocator::TAllocFail
  1619 */
  1620 #define __UHEAP_CHECKFAILURE User::__DbgCheckFailure(FALSE)
  1621 
  1622 /**
  1623 @publishedAll
  1624 @released
  1625 
  1626 Returns the number of kernel heap allocation failures the current debug 
  1627 allocator fail function has caused so far.
  1628 
  1629 This is intended to only be used with fail types RAllocator::EFailNext,
  1630 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  1631 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  1632 all other fail types.
  1633 
  1634 @return The number of heap allocation failures the current debug fail 
  1635 function has caused.
  1636 
  1637 @see RAllocator::TAllocFail
  1638 */
  1639 #define __KHEAP_CHECKFAILURE User::__DbgCheckFailure(TRUE)
  1640 
  1641 
  1642 
  1643 /**
  1644 @publishedAll
  1645 @released
  1646 
  1647 Marks the start of heap checking for the specific heap. 
  1648 
  1649 This macro is defined only for debug builds.
  1650 
  1651 This macro must be matched by a corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
  1652 
  1653 Calls to this macro can be nested but each call must be matched by corresponding 
  1654 call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
  1655 
  1656 @param aHeap A pointer to the specific RHeap
  1657 
  1658 @see RHeap
  1659 @see RAllocator::__DbgMarkStart()
  1660 @see __RHEAP_MARKEND
  1661 @see __RHEAP_MARKENDC
  1662 */
  1663 #define __RHEAP_MARK(aHeap) (aHeap)->__DbgMarkStart()
  1664 
  1665 
  1666 
  1667 
  1668 /**
  1669 @publishedAll
  1670 @released
  1671 
  1672 Checks that the number of allocated cells at the current nested level on the 
  1673 specified heap is the same as the specified value. 
  1674 
  1675 The macro also takes the name of the file containing this source code statement 
  1676 and the line number of this source code statement; they are displayed as part 
  1677 of the panic category, if the checks fail. 
  1678 
  1679 This macro is defined only for debug builds.
  1680 
  1681 @param aHeap  A pointer to the specific RHeap.
  1682 @param aCount The number of heap cells expected to be allocated at
  1683               the current nest level.
  1684 
  1685 @see RAllocator::__DbgMarkCheck()
  1686 */
  1687 #define __RHEAP_CHECK(aHeap,aCount) (aHeap)->__DbgMarkCheck(FALSE,aCount,(TText8*)__FILE__,__LINE__)
  1688 
  1689 
  1690 
  1691 
  1692 /**
  1693 @publishedAll
  1694 @released
  1695 
  1696 Checks that the total number of allocated cells on the specified heap is the 
  1697 same as the specified value.
  1698 
  1699 The macro also takes the name of the file containing this source code statement 
  1700 and the line number of this source code statement; they are displayed as part 
  1701 of the panic category, if the checks fail.
  1702 
  1703 This macro is defined only for debug builds.
  1704 
  1705 @param aHeap  A pointer to the specific RHeap.
  1706 @param aCount The total number of heap cells expected to be allocated.
  1707 
  1708 @see RAllocator::__DbgMarkCheck()
  1709 */
  1710 #define __RHEAP_CHECKALL(aHeap,aCount) (aHeap)->__DbgMarkCheck(TRUE,aCount,(TText8*)__FILE__,__LINE__)
  1711 
  1712 
  1713 
  1714 
  1715 /**
  1716 @publishedAll
  1717 @released
  1718 
  1719 Marks the end of heap checking for the specific heap.
  1720 
  1721 The macro expects zero heap cells to remain allocated at the current nest 
  1722 level. This macro is defined only for debug builds.
  1723 
  1724 This macro must match an earlier call to __RHEAP_MARK.
  1725 
  1726 @param aHeap A pointer to the specific RHeap.
  1727 
  1728 @see RAllocator::__DbgMarkEnd()
  1729 @see __RHEAP_MARK
  1730 */
  1731 #define __RHEAP_MARKEND(aHeap) (aHeap)->__DbgMarkEnd(0)
  1732 
  1733 
  1734 
  1735 
  1736 /**
  1737 @publishedAll
  1738 @released
  1739 
  1740 Marks the end of heap checking for the specific heap.
  1741 
  1742 The macro expects aCount heap cells to remain allocated at the current nest 
  1743 level. This macro is defined only for debug builds.
  1744 
  1745 This macro must match an earlier call to __RHEAP_MARK.
  1746 
  1747 @param aHeap  A pointer to the specific RHeap.
  1748 @param aCount The number of heap cells expected to remain allocated at
  1749               the current nest level
  1750 
  1751 @see RAllocator::__DbgMarkEnd()
  1752 @see __RHEAP_MARK
  1753 */
  1754 #define __RHEAP_MARKENDC(aHeap,aCount) (aHeap)->__DbgMarkEnd(aCount)
  1755 
  1756 
  1757 
  1758 
  1759 /**
  1760 @publishedAll
  1761 @released
  1762 
  1763 Simulates an allocation failure for the specific heap.
  1764 
  1765 The failure occurs on the next call to new or any of the functions which allocate 
  1766 memory from the heap. This macro is defined only for debug builds.
  1767 
  1768 @param aHeap  A pointer to the specific RHeap.
  1769 @param aCount The rate of failure - heap allocation fails every aCount attempt.
  1770 
  1771 @see RAllocator::__DbgSetAllocFail()
  1772 */
  1773 #define __RHEAP_FAILNEXT(aHeap,aCount) (aHeap)->__DbgSetAllocFail(RAllocator::EFailNext,aCount)
  1774 
  1775 /**
  1776 @publishedAll
  1777 @released
  1778 
  1779 Simulates aBurst allocation failures for the specific heap.
  1780 
  1781 The failure occurs on the next call to new or any of the functions which allocate 
  1782 memory from the heap. This macro is defined only for debug builds.
  1783 
  1784 @param aHeap  A pointer to the specific RHeap.
  1785 @param aCount The heap allocation will fail after aCount-1 allocation attempts. 
  1786               Note when used with RHeap the maximum value aCount can be set 
  1787               to is KMaxTUint16.
  1788 @param aBurst The number of consecutive allocations that will fail.  Note 
  1789               when used with RHeap the maximum value aBurst can be set 
  1790               to is KMaxTUint16.
  1791 
  1792 @see RAllocator::__DbgSetBurstAllocFail()
  1793 */
  1794 #define __RHEAP_BURSTFAILNEXT(aHeap,aCount,aBurst) (aHeap)->__DbgSetBurstAllocFail(RAllocator::EBurstFailNext,aCount, aBurst)
  1795 
  1796 
  1797 
  1798 /**
  1799 @publishedAll
  1800 @released
  1801 
  1802 Simulates an allocation failure for the specific heap. 
  1803 
  1804 The failure occurs on subsequent calls to new or any of the functions which 
  1805 allocate memory from the heap. This macro is defined only for debug builds.
  1806 
  1807 @param aHeap  A pointer to the specific RHeap.
  1808 @param aType  The type of failure to be simulated. 
  1809 @param aRate The failure rate.
  1810 
  1811 @see RAllocator::__DbgSetAllocFail()
  1812 */
  1813 #define __RHEAP_SETFAIL(aHeap,aType,aRate) (aHeap)->__DbgSetAllocFail(aType,aRate)
  1814 
  1815 /**
  1816 @publishedAll
  1817 @released
  1818 
  1819 Simulates an allocation failure for the specific heap. 
  1820 
  1821 The failure occurs on subsequent calls to new or any of the functions which 
  1822 allocate memory from the heap. This macro is defined only for debug builds.
  1823 
  1824 @param aHeap  A pointer to the specific RHeap.
  1825 @param aType  The type of failure to be simulated. 
  1826 @param aRate  The failure rate.  Note when used with RHeap the maximum value 
  1827               aRate can be set to is KMaxTUint16.
  1828 @param aBurst The number of consecutive allocations that will fail.  Note 
  1829               when used with RHeap the maximum value aBurst can be set 
  1830               to is KMaxTUint16.
  1831 
  1832 @see RAllocator::__DbgSetBurstAllocFail()
  1833 */
  1834 #define __RHEAP_SETBURSTFAIL(aHeap,aType,aRate,aBurst) (aHeap)->__DbgSetBurstAllocFail(aType,aRate,aBurst)
  1835 
  1836 
  1837 
  1838 /**
  1839 @publishedAll
  1840 @released
  1841 
  1842 Cancels simulated allocation failure for the specific heap.
  1843 
  1844 This macro is defined only for debug builds.
  1845 
  1846 @param aHeap A pointer to the specific RHeap.
  1847 
  1848 @see RAllocator::__DbgSetAllocFail()
  1849 */
  1850 #define __RHEAP_RESET(aHeap) (aHeap)->__DbgSetAllocFail(RAllocator::ENone,1)
  1851 
  1852 
  1853 
  1854 /**
  1855 @publishedAll
  1856 @released
  1857 
  1858 Cancels simulated allocation failure for the specific heap.
  1859 It walks the the heap and sets the nesting level for all allocated
  1860 cells to zero.
  1861 
  1862 This macro is defined only for debug builds.
  1863 
  1864 @param aHeap A pointer to the specific RHeap.
  1865 
  1866 @see RAllocator::__DbgSetAllocFail()
  1867 */
  1868 #define __RHEAP_TOTAL_RESET(aHeap) (aHeap)->__DbgSetAllocFail(RAllocator::EReset,1)
  1869 
  1870 /**
  1871 @publishedAll
  1872 @released
  1873 
  1874 Returns the number of heap allocation failures the current debug allocator fail
  1875 function has caused so far.
  1876 
  1877 This is intended to only be used with fail types RAllocator::EFailNext,
  1878 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  1879 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  1880 all other fail types.
  1881 
  1882 @return The number of heap allocation failures the current debug fail 
  1883 function has caused.
  1884 
  1885 @see RAllocator::TAllocFail
  1886 */
  1887 #define __RHEAP_CHECKFAILURE(aHeap) (aHeap)->__DbgCheckFailure()
  1888 
  1889 
  1890 #if defined (__WINS__) 
  1891 
  1892 /**
  1893 @publishedAll
  1894 @released
  1895 */
  1896 #define __DEBUGGER() {if (User::JustInTime()) __BREAKPOINT()}
  1897 
  1898 #else
  1899 #define __DEBUGGER()
  1900 #endif
  1901 
  1902 
  1903 #if defined(__DLL__)
  1904 /**
  1905 @publishedAll
  1906 @released
  1907 
  1908 Declares a function for testing object invariance.
  1909 
  1910 For complex classes, it is often useful to provide a function that can
  1911 be called to check that the object is in a valid state.
  1912 The __DECLARE_TEST macro supplies a standard prototype for such a function
  1913 named __DbgTestInvariant(). A companion macro __TEST_INVARIANT is provided
  1914 to call the function.
  1915 
  1916 For DLLs, as opposed to EXEs, __DbgTestInvariant() is exported,
  1917 i.e. the macro expands to:
  1918 
  1919 @code
  1920 public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
  1921 @endcode
  1922 
  1923 This macro should placed as the last item in a class declaration (as it 
  1924 switches back to public access). Note that a terminating semi-colon must be used.
  1925 
  1926 You should define the __DbgTestInvariant() function to check that the object
  1927 is in a healthy state. If it finds an error, it should call User::Invariant(),
  1928 which will cause a panic. 
  1929 
  1930 If a class is derived from a base class, then the base class __DbgTestInvariant()
  1931 should be called first, and then any further checking done. 
  1932 
  1933 The second function declared, __DbgTest(), is intended to allow test code a way
  1934 of directly accessing non-public members of a class. The function is
  1935 implemented by any test code that requires it, rather than in the class’s own
  1936 source code. The function is therefore not exported.
  1937 
  1938 __DECLARE_TEST is defined for both debug and release builds. This point is
  1939 particularly important for DLLs, as otherwise the exported interfaces would
  1940 differ between the build versions, giving potential binary compatibility
  1941 problems. To avoid using memory unnecessarily in release builds, you can,
  1942 however, use preprocessor directives to define the code within
  1943 __DbgTestInvariant() only for debug builds. __DbgTestInvariant() is never
  1944 called in release builds.
  1945 
  1946 @see __TEST_INVARIANT
  1947 */
  1948 #define __DECLARE_TEST public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
  1949 #else
  1950 #define __DECLARE_TEST public: void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
  1951 #endif
  1952 
  1953 #else
  1954 #define __ASSERT_DEBUG(c,p)
  1955 #define __DECLARE_NAME(t)
  1956 #define __TEST_INVARIANT
  1957 #if defined(__DLL__)
  1958 #define __DECLARE_TEST public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
  1959 #else
  1960 #define __DECLARE_TEST public: void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const
  1961 #endif
  1962 
  1963 
  1964 
  1965 
  1966 /**
  1967 @publishedAll
  1968 @released
  1969 
  1970 Marks the start of checking the current thread's heap. 
  1971 
  1972 This macro is defined only for debug builds.
  1973 
  1974 This macro must be matched by a corresponding call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
  1975 
  1976 Calls to this macro can be nested but each call must be matched by corresponding 
  1977 call to __UHEAP_MARKEND or __UHEAP_MARKENDC.
  1978 
  1979 @see User::__DbgMarkStart()
  1980 @see __UHEAP_MARKEND
  1981 @see __UHEAP_MARKENDC
  1982 */
  1983 #define __UHEAP_MARK
  1984 
  1985 
  1986 
  1987 
  1988 /**
  1989 @publishedAll
  1990 @released
  1991 
  1992 Checks that the number of allocated cells at the current nested level on the 
  1993 current thread's heap is the same as the specified value.
  1994 
  1995 This macro is defined only for debug builds.
  1996 
  1997 The macro also takes the name of the file containing this source code statement 
  1998 and the line number of this source code statement; they are displayed as part 
  1999 of the panic category, if the checks fail.
  2000 
  2001 The macro assumes that:
  2002 
  2003 1. the heap being checked is a user heap
  2004 
  2005 2. checking is being done for the number of allocated cells at the current nested 
  2006    level; i.e. that aCountAll is set to false
  2007 
  2008 3. the line number is the line number of this source code statement.
  2009 
  2010 4. the file name is the full path name of the file containing this source statement
  2011 
  2012 @param aCount The number of heap cells expected to be allocated at
  2013               the current nest level.
  2014 
  2015 @see User::__DbgMarkCheck()
  2016 @see __KHEAP_CHECK
  2017 */
  2018 #define __UHEAP_CHECK(aCount)
  2019 
  2020 
  2021 
  2022 
  2023 /**
  2024 @publishedAll
  2025 @released
  2026 
  2027 Checks that the total number of allocated cells on the current thread's heap 
  2028 is the same as the specified value.
  2029 
  2030 This macro is defined only for debug builds.
  2031 
  2032 The macro also takes the name of the file containing this source code statement 
  2033 and the line number of this source code statement; they are displayed as part 
  2034 of the panic category, if the checks fail.
  2035 
  2036 @param aCount The total number of heap cells expected to be allocated.
  2037 
  2038 @see User::__DbgMarkCheck()
  2039 @see __KHEAP_CHECKALL
  2040 */
  2041 #define __UHEAP_CHECKALL(aCount)
  2042 
  2043 
  2044 
  2045 
  2046 /**
  2047 @publishedAll
  2048 @released
  2049 
  2050 Marks the end of checking the current thread's heap. 
  2051 
  2052 The macro expects zero heap cells to remain allocated at the current nest 
  2053 level. This macro is defined only for debug builds.
  2054 
  2055 This macro must match an earlier call to __UHEAP_MARK.
  2056 
  2057 @see User::__DbgMarkEnd()
  2058 @see __UHEAP_MARK
  2059 */
  2060 #define __UHEAP_MARKEND
  2061 
  2062 
  2063 
  2064 
  2065 /**
  2066 @publishedAll
  2067 @released
  2068 
  2069 Marks the end of checking the current thread's heap. 
  2070 
  2071 The macro expects aCount heap cells to remain allocated at the current nest 
  2072 level.
  2073 
  2074 This macro must match an earlier call to __UHEAP_MARK.
  2075 
  2076 @param aCount The number of heap cells expected to remain allocated at
  2077               the current nest level.
  2078 
  2079 @see User::__DbgMarkEnd()
  2080 @see __UHEAP_MARK
  2081 */
  2082 #define __UHEAP_MARKENDC(aCount)
  2083 
  2084 
  2085 
  2086 
  2087 /**
  2088 @publishedAll
  2089 @released
  2090 
  2091 Simulates heap allocation failure for the current thread's heap.
  2092 
  2093 The failure occurs on the next call to new or any of the functions which 
  2094 allocate memory from the heap. This macro is defined only for debug builds.
  2095 
  2096 @param aCount Determines when the allocation will fail.
  2097               Heap allocation fails on attempt number aCount - later
  2098               allocations will succeed.
  2099               For example, if aCount is 3, then heap allocation fails
  2100               on the 3rd attempt, but all subsequent allocations succeed. 
  2101 
  2102 @see User::__DbgSetAllocFail()
  2103 */
  2104 #define __UHEAP_FAILNEXT(aCount)
  2105 
  2106 /**
  2107 @publishedAll
  2108 @released
  2109 
  2110 Simulates heap allocation failure for the current thread's heap.
  2111 
  2112 The failures will occur for aBurst times from the next call to new or any of the functions which 
  2113 allocate memory from the heap. This macro is defined only for debug builds.
  2114 
  2115 @param aCount Determines when the allocation will fail.
  2116               Heap allocation fails on attempt number aCount - later
  2117               allocations will succeed.
  2118               For example, if aCount is 3, then heap allocation fails
  2119               on the 3rd attempt, but all subsequent allocations succeed.   
  2120               Note when used with RHeap the maximum value aBurst can be 
  2121               set to is KMaxTUint16.
  2122 @param aBurst The number of consecutive allocations that will fail.  Note 
  2123               when used with RHeap the maximum value aBurst can be set 
  2124               to is KMaxTUint16.
  2125 
  2126 @see User::__DbgSetBurstAllocFail()
  2127 */
  2128 #define __UHEAP_BURSTFAILNEXT(aCount,aBurst)
  2129 
  2130 
  2131 
  2132 /**
  2133 @publishedAll
  2134 @released
  2135 
  2136 Simulates heap allocation failure for the current thread's heap. 
  2137 
  2138 The failure occurs on subsequent calls to new or any of the functions which 
  2139 allocate memory from the heap. This macro is defined only for debug builds.
  2140 
  2141 @param aType  The type of failure to be simulated.
  2142 @param aRate The failure rate.
  2143 
  2144 @see User::__DbgSetAllocFail()
  2145 */
  2146 #define __UHEAP_SETFAIL(aType,aRate)
  2147 
  2148 /**
  2149 @publishedAll
  2150 @released
  2151 
  2152 Simulates heap allocation failure for the current thread's heap. 
  2153 
  2154 The failure occurs on subsequent calls to new or any of the functions which 
  2155 allocate memory from the heap. This macro is defined only for debug builds.
  2156 
  2157 @param aType  The type of failure to be simulated.
  2158 @param aRate  The failure rate.  Note when used with RHeap the maximum value 
  2159               aRate can be set to is KMaxTUint16.
  2160 @param aBurst The number of consecutive allocations that will fail.  Note 
  2161               when used with RHeap the maximum value aBurst can be set 
  2162               to is KMaxTUint16.
  2163 
  2164 @see User::__DbgSetBurstAllocFail()
  2165 @see RAllocator::TAllocFail
  2166 */
  2167 #define __UHEAP_SETBURSTFAIL(aType,aRate,aBurst)
  2168 
  2169 
  2170 
  2171 /**
  2172 @publishedAll
  2173 @released
  2174 
  2175 Cancels simulated heap allocation failure for the current thread's heap. 
  2176 
  2177 This macro is defined only for debug builds.
  2178 
  2179 @see User::__DbgSetAllocFail()
  2180 */
  2181 #define __UHEAP_RESET
  2182 
  2183 
  2184 
  2185 /**
  2186 @publishedAll
  2187 @released
  2188 
  2189 Cancels simulated heap allocation failure for the current thread's heap. 
  2190 It walks the the heap and sets the nesting level for all allocated
  2191 cells to zero.
  2192 
  2193 This macro is defined only for debug builds.
  2194 */
  2195 #define __UHEAP_TOTAL_RESET
  2196 
  2197 /**
  2198 @publishedAll
  2199 @released
  2200 
  2201 Returns the number of heap allocation failures the current debug allocator fail
  2202 function has caused so far.
  2203 
  2204 This is intended to only be used with fail types RAllocator::EFailNext,
  2205 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  2206 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  2207 all other fail types.
  2208 
  2209 @return The number of heap allocation failures the current debug fail 
  2210 function has caused.
  2211 
  2212 @see RAllocator::TAllocFail
  2213 */
  2214 #define __UHEAP_CHECKFAILURE ((TUint)0)
  2215 
  2216 /**
  2217 @publishedAll
  2218 @released
  2219 
  2220 Returns the number of kernel heap allocation failures the current debug 
  2221 allocator fail function has caused so far.
  2222 
  2223 This is intended to only be used with fail types RAllocator::EFailNext,
  2224 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  2225 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  2226 all other fail types.
  2227 
  2228 @return The number of heap allocation failures the current debug fail 
  2229 function has caused.
  2230 
  2231 @see RAllocator::TAllocFail
  2232 */
  2233 #define __KHEAP_CHECKFAILURE ((TUint)0)
  2234 
  2235 /**
  2236 @publishedAll
  2237 @released
  2238 
  2239 Marks the start of heap checking for the specific heap. 
  2240 
  2241 This macro is defined only for debug builds.
  2242 
  2243 This macro must be matched by a corresponding call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
  2244 
  2245 Calls to this macro can be nested but each call must be matched by corresponding 
  2246 call to __RHEAP_MARKEND or __RHEAP_MARKENDC.
  2247 
  2248 @param aHeap A pointer to the specific RHeap
  2249 
  2250 @see RHeap
  2251 @see RAllocator::__DbgMarkStart()
  2252 @see __RHEAP_MARKEND
  2253 @see __RHEAP_MARKENDC
  2254 */
  2255 #define __RHEAP_MARK(aHeap)
  2256 
  2257 
  2258 
  2259 
  2260 /**
  2261 @publishedAll
  2262 @released
  2263 
  2264 Checks that the number of allocated cells at the current nested level on the 
  2265 specified heap is the same as the specified value. 
  2266 
  2267 The macro also takes the name of the file containing this source code statement 
  2268 and the line number of this source code statement; they are displayed as part 
  2269 of the panic category, if the checks fail. 
  2270 
  2271 This macro is defined only for debug builds.
  2272 
  2273 @param aHeap  A pointer to the specific RHeap.
  2274 @param aCount The number of heap cells expected to be allocated at
  2275               the current nest level.
  2276 
  2277 @see RAllocator::__DbgMarkCheck()
  2278 */
  2279 #define __RHEAP_CHECK(aHeap,aCount)
  2280 
  2281 
  2282 
  2283 
  2284 /**
  2285 @publishedAll
  2286 @released
  2287 
  2288 Checks that the total number of allocated cells on the specified heap is the 
  2289 same as the specified value.
  2290 
  2291 The macro also takes the name of the file containing this source code statement 
  2292 and the line number of this source code statement; they are displayed as part 
  2293 of the panic category, if the checks fail.
  2294 
  2295 This macro is defined only for debug builds.
  2296 
  2297 @param aHeap  A pointer to the specific RHeap.
  2298 @param aCount The total number of heap cells expected to be allocated.
  2299 
  2300 @see RAllocator::__DbgMarkCheck()
  2301 */
  2302 #define __RHEAP_CHECKALL(aHeap,aCount)
  2303 
  2304 
  2305 
  2306 
  2307 /**
  2308 @publishedAll
  2309 @released
  2310 
  2311 Marks the end of heap checking for the specific heap.
  2312 
  2313 The macro expects zero heap cells to remain allocated at the current nest 
  2314 level. This macro is defined only for debug builds.
  2315 
  2316 This macro must match an earlier call to __RHEAP_MARK.
  2317 
  2318 @param aHeap A pointer to the specific RHeap.
  2319 
  2320 @see RAllocator::__DbgMarkEnd()
  2321 @see __RHEAP_MARK
  2322 */
  2323 #define __RHEAP_MARKEND(aHeap)
  2324 
  2325 
  2326 
  2327 
  2328 /**
  2329 @publishedAll
  2330 @released
  2331 
  2332 Marks the end of heap checking for the specific heap.
  2333 
  2334 The macro expects aCount heap cells to remain allocated at the current nest 
  2335 level. This macro is defined only for debug builds.
  2336 
  2337 This macro must match an earlier call to __RHEAP_MARK.
  2338 
  2339 @param aHeap  A pointer to the specific RHeap.
  2340 @param aCount The number of heap cells expected to remain allocated at
  2341               the current nest level
  2342 
  2343 @see RAllocator::__DbgMarkEnd()
  2344 @see __RHEAP_MARK
  2345 */
  2346 #define __RHEAP_MARKENDC(aHeap,aCount)
  2347 
  2348 
  2349 
  2350 
  2351 /**
  2352 @publishedAll
  2353 @released
  2354 
  2355 Simulates an allocation failure for the specific heap.
  2356 
  2357 The failure occurs on the next call to new or any of the functions which allocate 
  2358 memory from the heap. This macro is defined only for debug builds.
  2359 
  2360 @param aHeap  A pointer to the specific RHeap.
  2361 @param aCount The rate of failure - heap allocation fails every aCount attempt.
  2362 
  2363 @see RAllocator::__DbgSetAllocFail()
  2364 */
  2365 #define __RHEAP_FAILNEXT(aHeap,aCount)
  2366 
  2367 /**
  2368 @publishedAll
  2369 @released
  2370 
  2371 Simulates aBurst allocation failures for the specific heap.
  2372 
  2373 The failure occurs on the next call to new or any of the functions which allocate 
  2374 memory from the heap. This macro is defined only for debug builds.
  2375 
  2376 @param aHeap  A pointer to the specific RHeap.
  2377 @param aCount The heap allocation will fail after aCount-1 allocation attempts. 
  2378               Note when used with RHeap the maximum value aCount can be set 
  2379               to is KMaxTUint16.
  2380 @param aBurst The number of consecutive allocations that will fail.  Note 
  2381               when used with RHeap the maximum value aBurst can be set 
  2382               to is KMaxTUint16.
  2383 
  2384 @see RAllocator::__DbgSetBurstAllocFail()
  2385 */
  2386 #define __RHEAP_BURSTFAILNEXT(aHeap,aCount,aBurst)
  2387 
  2388 
  2389 
  2390 /**
  2391 @publishedAll
  2392 @released
  2393 
  2394 Simulates an allocation failure for the specific heap. 
  2395 
  2396 The failure occurs on subsequent calls to new or any of the functions which 
  2397 allocate memory from the heap. This macro is defined only for debug builds.
  2398 
  2399 @param aHeap  A pointer to the specific RHeap.
  2400 @param aType  The type of failure to be simulated. 
  2401 @param aRate The failure rate.
  2402 
  2403 @see RAllocator::__DbgSetAllocFail()
  2404 */
  2405 #define __RHEAP_SETFAIL(aHeap,aType,aRate)
  2406 
  2407 /**
  2408 @publishedAll
  2409 @released
  2410 
  2411 Simulates an allocation failure for the specific heap. 
  2412 
  2413 The failure occurs on subsequent calls to new or any of the functions which 
  2414 allocate memory from the heap. This macro is defined only for debug builds.
  2415 
  2416 @param aHeap  A pointer to the specific RHeap.
  2417 @param aType  The type of failure to be simulated. 
  2418 @param aRate  The failure rate.  Note when used with RHeap the maximum value 
  2419               aRate can be set to is KMaxTUint16.
  2420 @param aBurst The number of consecutive allocations that will fail.  Note 
  2421               when used with RHeap the maximum value aBurst can be set 
  2422               to is KMaxTUint16.
  2423 
  2424 @see RAllocator::__DbgSetBurstAllocFail()
  2425 */
  2426 #define __RHEAP_SETBURSTFAIL(aHeap,aType,aRate,aBurst)
  2427 
  2428 
  2429 
  2430 /**
  2431 @publishedAll
  2432 @released
  2433 
  2434 Cancels simulated allocation failure for the specific heap.
  2435 
  2436 This macro is defined only for debug builds.
  2437 
  2438 @param aHeap A pointer to the specific RHeap.
  2439 
  2440 @see RAllocator::__DbgSetAllocFail()
  2441 */
  2442 #define __RHEAP_RESET(aHeap)
  2443 
  2444 
  2445 
  2446 /**
  2447 @publishedAll
  2448 @released
  2449 
  2450 Cancels simulated allocation failure for the specific heap.
  2451 It walks the the heap and sets the nesting level for all allocated
  2452 cells to zero.
  2453 
  2454 This macro is defined only for debug builds.
  2455 
  2456 @param aHeap A pointer to the specific RHeap.
  2457 
  2458 @see RAllocator::__DbgSetAllocFail()
  2459 */
  2460 #define __RHEAP_TOTAL_RESET(aHeap)
  2461 
  2462 
  2463 /**
  2464 @publishedAll
  2465 @released
  2466 
  2467 Returns the number of heap allocation failures the current debug allocator fail
  2468 function has caused so far.
  2469 
  2470 This is intended to only be used with fail types RAllocator::EFailNext,
  2471 RAllocator::EBurstFailNext, RAllocator::EDeterministic and
  2472 RAllocator::EBurstDeterministic.  The return value is unreliable for 
  2473 all other fail types.
  2474 
  2475 @return The number of heap allocation failures the current debug fail 
  2476 function has caused.
  2477 
  2478 @see RAllocator::TAllocFail
  2479 */
  2480 #define __RHEAP_CHECKFAILURE(aHeap) ((TUint)0)
  2481 
  2482 #define __DEBUGGER()
  2483 #endif
  2484 
  2485 #if defined (__WINS__)
  2486 /** @internalTechnology */
  2487 #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};
  2488 /** @internalTechnology */
  2489 #define __EMULATOR_IMAGE_HEADER(aUid0,aUid1,aUid2,aPriority,aCap,aFlags)					TEmulatorImageHeader uid={{aUid0,aUid1,aUid2},aPriority,{aUid2,0,{aCap,0}},0,0,0x00010000u,aFlags};
  2490 #else
  2491 #define __EMULATOR_IMAGE_HEADER2(aUid0,aUid1,aUid2,aPriority,aCap0,aCap1,aSid,aVer,aFlags)
  2492 #define __EMULATOR_IMAGE_HEADER(aUid0,aUid1,aUid2,aPriority,aCap,aFlags)
  2493 #endif
  2494 
  2495 #if defined(_UNICODE)
  2496 #if !defined(UNICODE)
  2497 /**
  2498 @publishedAll
  2499 @deprecated
  2500 */
  2501 #define UNICODE
  2502 #endif
  2503 #endif
  2504 
  2505 #if !defined(ASSERT)
  2506 /**
  2507 @publishedAll
  2508 @released
  2509 
  2510 Generates _ASSERT_DEBUG code that calls User::Invariant() if the specified
  2511 condition is not true.
  2512 
  2513 @param x A conditional expression which results in true or false.
  2514 */
  2515 #define ASSERT(x) __ASSERT_DEBUG(x,User::Invariant())
  2516 #endif
  2517 
  2518 
  2519 
  2520 
  2521 #if defined(_DEBUG)
  2522 /**
  2523 @publishedAll
  2524 @released
  2525 */
  2526 #define __DEBUG_ONLY(x) x
  2527 #else
  2528 #define __DEBUG_ONLY(x)
  2529 #endif
  2530 
  2531 
  2532 
  2533 
  2534 #ifdef __KERNEL_MODE__
  2535 
  2536 /** @internalComponent */
  2537 #define	KIMPORT_C	IMPORT_C
  2538 
  2539 /** @internalComponent */
  2540 #define	KEXPORT_C	EXPORT_C
  2541 
  2542 /** @internalComponent */
  2543 #define	UIMPORT_C
  2544 
  2545 /** @internalComponent */
  2546 #define	UEXPORT_C
  2547 #else
  2548 #define	KIMPORT_C
  2549 #define	KEXPORT_C
  2550 #define	UIMPORT_C	IMPORT_C
  2551 #define	UEXPORT_C	EXPORT_C
  2552 #endif
  2553 
  2554 
  2555 
  2556 
  2557 /**
  2558 @publishedAll
  2559 @released
  2560 
  2561 Asserts that a condition is true at compilation time.
  2562 
  2563 @param x Condition to assert
  2564 */
  2565 #define __ASSERT_COMPILE(x)		void __compile_time_assert(int __check[(x)?1:-1])
  2566 
  2567 #ifdef __REMOVE_PLATSEC_DIAGNOSTICS__
  2568 /**
  2569 @publishedPartner
  2570 @released
  2571 */
  2572 #ifndef __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
  2573 #define __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
  2574 #endif /*__REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__*/
  2575 #endif /*__REMOVE_PLATSEC_DIAGNOSTICS__*/
  2576 
  2577 /**
  2578 @internalComponent
  2579 */
  2580 static const char* const KSuppressPlatSecDiagnosticMagicValue = (const char*)1;
  2581 
  2582 #ifndef __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__
  2583 /**
  2584 @internalComponent
  2585 */
  2586 #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER(l) #l
  2587 /**
  2588 @internalComponent
  2589 */
  2590 #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER2(f,l) f "(" __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER(l) ")"
  2591 /**
  2592 @publishedPartner
  2593 @released
  2594 */
  2595 #define __PLATSEC_DIAGNOSTIC_FILE_AND_LINE __PLATSEC_DIAGNOSTIC_FILE_AND_LINE_HELPER2(__FILE__,__LINE__)
  2596 
  2597 /**
  2598 @publishedPartner
  2599 @released
  2600 
  2601 A macro that should be used to enclose a platform security diagnostic
  2602 'C' style string that can be passed to a capability checking function such
  2603 as RThread::HasCapability() and Kern::CurrentThreadHasCapability().
  2604 
  2605 The content of the string is emitted if the capability test finds that
  2606 the capability is not present.
  2607 
  2608 The macro provides a convenient mechanism that allows the strings to
  2609 be removed from future versions of Symbian OS.
  2610 
  2611 For example:
  2612 
  2613 @code
  2614 if(!Kern::CurrentThreadHasCapability(ECapabilityPowerMgmt,__PLATSEC_DIAGNOSTIC_STRING("Checked by Hal function EDisplayHalSetState")))
  2615     {
  2616     return KErrPermissionDenied;
  2617     }			
  2618 @endcode
  2619 
  2620 In this example, the string:
  2621 
  2622 @code
  2623 Checked by Hal function EDisplayHalSetState
  2624 @endcode
  2625 
  2626 is emitted if the calling process does not have the ECapabilityPowerMgmt capability.
  2627 
  2628 @param s A C-style string.
  2629 
  2630 @see RProcess::HasCapability()
  2631 @see RThread::HasCapability()
  2632 @see RMessagePtr2::HasCapability()
  2633 @see User::CreatorHasCapability()
  2634 */
  2635 #define __PLATSEC_DIAGNOSTIC_STRING(s) s
  2636 
  2637 /**
  2638 When this value is used in Platform Security APIs as the value for the aDiagnosticText
  2639 argument, these APIs will not emit any form of diagnostic message.
  2640 @publishedPartner
  2641 @released
  2642 */
  2643 // Note this value is the same as KSuppressPlatSecDiagnosticMagicValue
  2644 // and used to be a set by it but that caused an error with GCCE compiler
  2645 static const char* const KSuppressPlatSecDiagnostic = (const char*)1;
  2646 
  2647 #else /* __REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__ */
  2648 
  2649 #define __PLATSEC_DIAGNOSTIC_STRING(s) NULL
  2650 
  2651 #ifndef __KERNEL_MODE__
  2652 #ifndef __REMOVE_PLATSEC_DIAGNOSTICS__
  2653 /**
  2654 When this value is used in Platform Security APIs as the value for the aDiagnostic
  2655 argument, these APIs will not emit any form of diagnostic message.
  2656 @publishedPartner
  2657 @released
  2658 */
  2659 #define KSuppressPlatSecDiagnostic		NULL, NULL
  2660 
  2661 #else /* __REMOVE_PLATSEC_DIAGNOSTICS__ */
  2662 
  2663 /**
  2664 When this value is used in Platform Security APIs as the value for the aDiagnostic
  2665 argument, these APIs will not emit any form of diagnostic message.
  2666 @publishedPartner
  2667 @released
  2668 */
  2669 #define KSuppressPlatSecDiagnostic		NULL
  2670 
  2671 #endif /* !__REMOVE_PLATSEC_DIAGNOSTICS__ */
  2672 #endif /* !__KERNEL_MODE__ */
  2673 #endif /* !__REMOVE_PLATSEC_DIAGNOSTIC_STRINGS__ */
  2674 
  2675 /*
  2676  * MSVC operator new and operator new[] header guards
  2677  */
  2678 #ifdef __PLACEMENT_NEW
  2679 #define __PLACEMENT_NEW_INLINE
  2680 #endif /* __PLACEMENT_NEW */
  2681 
  2682 #if defined(__VC32__) && (_MSC_VER < 1300)
  2683 #define __PLACEMENT_VEC_NEW_INLINE
  2684 #define __OMIT_VEC_OPERATOR_NEW_DECL__
  2685 #endif /* version of MSVC that doesn't support overloaded operator new[] */
  2686 
  2687 /**
  2688 Calling convention qualifier for functions involving floating point 
  2689 variables passed or returned by value.
  2690 @publishedAll
  2691 @released
  2692 */
  2693 #ifndef __SOFTFP
  2694 #define __SOFTFP
  2695 #endif /* __SOFTFP */
  2696 
  2697 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
  2698 #include <e32def_private.h>
  2699 #endif
  2700 
  2701 #endif /* __E32DEF_H__ */