User Class Reference

aSize

)

[static]

Allocates a cell of specified size from the current thread's heap.

If there is insufficient memory available on the heap from which to allocate a cell of the required size, the function returns NULL.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

Parameters
aSize	The size of the cell to be allocated from the current thread's heap.

Return Value: A pointer to the allocated cell. NULL, if there is insufficient memory available.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocAligned ( TInt, TInt )

IMPORT_C TAny *	AllocAligned	(	TInt	aAlignment,
			TInt	aSize
		)	[static]

Allocates a cell with specified size from heap which is aligned in accord with the alignment argument. The alignment argument should be a power of two. If the argument is not a power of two, the nearest greater power is used.

Parameters
aAlignment	Alignment value which should power of two.
aSize	The size of the cell to be allocated from the current thread's heap.

Return Value: A pointer to the allocated cell. NULL, if there is insufficient memory available.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocL ( TInt )

IMPORT_C TAny *

AllocL

(

aSize

)

[static]

Allocates a cell of specified size from the current thread's heap, and leaves if there is insufficient memory in the heap.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

Parameters
aSize	The size of the cell to be allocated from the current thread's heap.

Return Value: A pointer to the allocated cell.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocLC ( TInt )

IMPORT_C TAny *

AllocLC

(

aSize

)

[static]

Allocates a cell of specified size from the current thread's default heap, and, if successful, places a pointer to the cell onto the cleanup stack.

The function leaves if there is insufficient memory in the heap.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

Parameters
aSize	The size of the cell to be allocated from the current thread's default heap.

Return Value: A pointer to the allocated cell.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocLen ( const TAny * )

IMPORT_C TInt

AllocLen

(

const TAny *

aCell

)

[static]

Gets the length of the specified allocated heap cell.

The cell is assumed to be in the current thread's heap.

Parameters
aCell	A pointer to the allocated cell whose length is to be fetched.

Return Value: The length of the allocated cell.

AllocSize ( TInt & )

IMPORT_C TInt

AllocSize

(

TInt &

aTotalAllocSize

)

[static]

Gets the total number of cells allocated on the current thread's default heap, and the total space allocated to them.

Parameters
aTotalAllocSize	On return, contains the total space allocated to the cells.

Return Value: The number of cells currently allocated on the current thread's heap.

AllocZ ( TInt )

IMPORT_C TAny *

AllocZ

(

aSize

)

[static]

Allocates a cell of specified size from the current thread's default heap, and clears it to binary zeroes.

If there is insufficient memory available on the heap from which to allocate a cell of the required size, the function returns NULL.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

Parameters
aSize	The size of the cell to be allocated from the current thread's default heap.

Return Value: A pointer to the allocated cell. NULL, if there is insufficient memory available.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocZL ( TInt )

IMPORT_C TAny *

AllocZL

(

aSize

)

[static]

Allocates a cell of specified size from the current thread's default heap, clears it to binary zeroes, and leaves if there is insufficient memory in the heap.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

Parameters
aSize	The size of the cell to be allocated from the current thread's heap.

Return Value: A pointer to the allocated cell.

Panic Codes
USER	47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

Allocator ( )

IMPORT_C RAllocator &

Allocator

(

)

[static]

Gets the current thread's default current heap.

Return Value: The current heap.

At ( const TTime & )

IMPORT_C TInt

(

const TTime &

aTime

)

[static]

Suspends the current thread until the specified absolute time, in the current time zone.

If the machine is off at that time, the machine will be turned on again.

KErrNone - suspension of the current thread completed normally at the requested time.

KErrAbort - suspension of the current thread was aborted because the system time changed.

KErrUnderflow - the requested completion time is in the past.

KErrOverFlow - the requested completion time is too far in the future.

Parameters
aTime	The absolute time, in the current time zone, until which the current thread is to be suspended.

Return Value: On completion, contains the status of the request to suspend the current thread:

Available ( TInt & )

IMPORT_C TInt

Available

(

TInt &

aBiggestBlock

)

[static]

Gets the total free space currently available on the current thread's default heap, and the space available in the largest free block.

The space available represents the total space which can be allocated.

Note that compressing the heap may reduce the total free space available and the space available in the largest free block.

Parameters
aBiggestBlock	On return, contains the space available in the largest free block on the current thread's default heap.

Return Value: The total free space currently available on the current thread's heap.

Beep ( TInt, TTimeIntervalMicroSeconds32 )

IMPORT_C TInt	Beep	(	TInt	aFrequency,
			TTimeIntervalMicroSeconds32	aDuration
		)	[static]

Makes a beep tone with a specified frequency and duration.

This function should not be used. It exists to maintain compatibility with older versions of Symban OS.

BinarySearch ( TInt, const TKey &, TInt & )

IMPORT_C TInt	BinarySearch	(	TInt	aCount,
			const TKey &	aKey,
			TInt &	aPos
		)	[static]

Performs a binary search for an array element containing a specified key.

It can be used on any kind of array where elements can be identified by key. It is used by the standard Symbian OS arrays having CArrayFix, CArrayVar or CArrayPak in their class hierarchy in the implementation of the various functions for inserting, deleting and finding elements by key. The function can be used by other arrays.

The function returns a zero value if the search is successful and a non-zero value otherwise.

If the search is successful, the function puts the position (i.e. the index) of the element into aPos. If the search is unsuccessful, then the function puts into aPos the position of the first element in the array whose key is greater than the search key.

If the array is empty, i.e. aCount is zero, then the search is unsuccessful and aPos is not defined.

Parameters
aCount	The number of elements in the array.
aKey	A reference to a suitably initialised TKey derived object. In particular, the object will have been initialised with a pointer to a sample element containing the search key.
aPos	If the element is found, the reference is set to the position of that element within the array. The position is relative to zero, (i.e. the first element in the array is at position 0). If the element is not found and the array is not empty, then the reference is set to the position of the first element in the array with a key which is greater than the search key. If the element is not found and the array is empty, then the reference is undefined.

Return Value: Zero, if the element with the specified key is found. Non-zero, if the element with the specified key is not found.

Panic Codes
USER	97, if aCount is negative.

CancelMiscNotifier ( TRequestStatus & )

IMPORT_C void

CancelMiscNotifier

(

TRequestStatus &

aStatus

)

[static]

Cancel a miscellaneous notification requested by this thread

Cancels a currently outstanding notification for system idle or object deletion.

Check ( )

IMPORT_C void

Check

(

)

[static]

Checks the validity of the current thread's default heap.

The function walks through the list of allocated cells and the list of free cells checking that the heap is consistent and complete.

Panic Codes
USER	47 if any corruption is found, specifically a bad allocated heap cell size.
USER	48 if any corruption is found, specifically a bad allocated heap cell address.
USER	49 if any corruption is found, specifically a bad free heap cell address.

Collate ( TUint )

IMPORT_C TUint

Collate

(

aChar

)

[static]

Converts the character to its collated form.

Collating is the process of removing differences between characters that are deemed unimportant for the purposes of ordering characters. The result of the conversion depends on the locale and on whether this is a UNICODE build or not.

Note that for a non UNICODE build, if the binary value of the character aChar is greater than or equal to 0x100, then the character returned is the same as the character passed to the function.

Parameters
aChar	The character to be folded.

Return Value: The converted character.

CommandLine ( TDes & )

IMPORT_C void

CommandLine

(

TDes &

aCommand

)

[static]

Gets a copy of the data which is passed as an argument to the thread function of the current process's main thread when it is first scheduled to run.

CommandLineLength ( )

IMPORT_C TInt

CommandLineLength

(

)

[static]

Gets the length of the data which is passed as an argument to the thread function of the current process's main thread when it is first scheduled to run.

Return Value: The length of the argument data.

CompressAllHeaps ( )

IMPORT_C TInt

CompressAllHeaps

(

)

[static]

Compresses all the chunks containing heaps.

DeprecatedThis function is no longer supported, and calling it has no effect.

Return Value: KErrNone

CountAllocCells ( )

IMPORT_C TInt

CountAllocCells

(

)

[static]

Gets the total number of cells allocated on the current thread's default heap.

Return Value: The number of cells allocated on the current thread's default user heap.

CountAllocCells ( TInt & )

IMPORT_C TInt

CountAllocCells

(

TInt &

aFreeCount

)

[static]

Gets the the total number of cells allocated, and the number of free cells, on the current thread's default heap.

Parameters
aFreeCount	On return, contains the number of free cells on the current thread's default heap.

Return Value: The number of cells allocated on the current thread's default heap.

CreatorHasCapability ( TCapability, const char * )

TBool	CreatorHasCapability	(	TCapability	aCapability,
			const char *	aDiagnostic = 0
		)	[static, inline]

Check if the process that created the current process has a given capability

When a check fails the action taken is determined by the system wide Platform Security configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted. If PlatSecEnforcement is OFF, then this function will return ETrue even though the check failed.

Parameters
aCapability	The capability to test.
aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the test finds the capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

Return Value: ETrue if the creator process has the capability, EFalse otherwise.

CreatorHasCapability ( TCapability, TCapability, const char * )

TBool	CreatorHasCapability	(	TCapability	aCapability1,
			TCapability	aCapability2,
			const char *	aDiagnostic = 0
		)	[static, inline]

Check if the process that created the current process has both of the given capabilities

Parameters
aCapability1	The first capability to test.
aCapability2	The second capability to test.
aDiagnostic	A string that will be emitted along with any diagnostic message that may be issued if the test finds a capability is not present. This string must be enclosed in the __PLATSEC_DIAGNOSTIC_STRING macro which enables it to be easily removed from the system.

Return Value: ETrue if the creator process has both the capabilities, EFalse otherwise.

CreatorIdentity ( )

TUid

CreatorIdentity

(

)

[static, inline]

CreatorSecureId ( )

IMPORT_C TSecureId

CreatorSecureId

(

)

[static]

Return the Secure ID of the process that created the current process.

Return Value: The Secure ID.

CreatorVendorId ( )

IMPORT_C TVendorId

CreatorVendorId

(

)

[static]

Return the Vendor ID of the process that created the current process.

Return Value: The Vendor ID.

Critical ( )

IMPORT_C TCritical

Critical

(

)

[static]

Gets the critical state associated with the current thread.

Critical ( RThread )

IMPORT_C TCritical

Critical

(

RThread

aThread

)

[static]

Gets the critical state associated with the specified thread.

ExceptionHandler ( )

IMPORT_C TExceptionHandler

ExceptionHandler

(

)

[static]

Gets a pointer to the exception handler for the current thread.

Return Value: A pointer to the exception handler.

Exit ( TInt )

IMPORT_C void

Exit

(

aReason

)

[static]

Terminates the current thread, specifying a reason. All child threads are terminated and all resources are cleaned up.

If the current thread is the main thread in a process, the process is also terminated.

Parameters
aReason	The reason code.

FastCounter ( )

IMPORT_C TUint32

FastCounter

(

)

[static]

Gets the fast counter.

This is the current value of the machine's high resolution timer. If a high resolution timer is not available, it uses the millisecond timer instead.

The freqency of this counter can be determined by reading the HAL attribute EFastCounterFrequency.

This function is intended for use in profiling and testing; it should not be used in production code. User::NTickCount() should be used instead.

This is because the implementation of the FastCounter is platform-specific: its frequency can be anywhere from a few KHz to many MHz. It may also not be activated when needed, since it is expensive in terms of clock cycles and battery life, and use of a platform-specific API may be necessary to enable it.

Fold ( TUint )

IMPORT_C TUint

Fold

(

aChar

)

[static]

Deprecated

Folds the specified character.

Folding converts the character to a form which can be used in tolerant comparisons without control over the operations performed. Tolerant comparisons are those which ignore character differences like case and accents.

The result of folding a character depends on the locale and on whether this is a UNICODE build or not.

Note that for a non-UNICODE build, if the binary value of the character aChar is greater than or equal to 0x100, then the character returned is the same as the character passed to the function.

Fold ( TUint, TInt )

IMPORT_C TUint	Fold	(	TUint	aChar,
			TInt	aFlags
		)	[static]

Folds the character according to a specified folding method.

TChar::EFoldCase, convert characters to their lower case form, if any;

TChar::EFoldAccents, strip accents;

TChar::EFoldDigits, convert digits representing values 0..9 to characters '0'..'9';

TChar::EFoldSpaces, convert all spaces (ordinary, fixed-width, ideographic, etc.) to ' ';

TChar::EFoldKana, convert hiragana to katakana;

TChar::EFoldWidth, fold full width and half width variants to their standard forms;

TChar::EFoldAll, use all of the above folding methods.

Free ( TAny * )

IMPORT_C void

Free

(

TAny *

aCell

)

[static]

Frees the specified cell and returns it to the current thread's default heap.

Parameters
aCell	A pointer to a valid cell to be freed. If NULL this function call will be ignored.

Panic Codes
USER	42, if aCell is not NULL and does not point to a valid cell.

FreeLogicalDevice ( const TDesC & )

IMPORT_C TInt

FreeLogicalDevice

(

const TDesC &

aDeviceName

)

[static]

Frees the logical device driver DLL associated with a specified driver name.

Parameters
aDeviceName	The name of the logical device driver object. This must match the name set during installation of the logical device. Typically, this is done in an implementation of DLogicalDevice::Install() through a call to SetName(). Note that the name is rarely the same as the device's filename. The name of a logical device driver object can be discovered by using TFindLogicalDevice.

Return Value: KErrNone if successful or one of the system-wide error codes. KErrNone will be returned if the device is not found as it may have already been freed.

FreePhysicalDevice ( const TDesC & )

IMPORT_C TInt

FreePhysicalDevice

(

const TDesC &

aDriverName

)

[static]

Frees the physical device driver DLL associated with a specified driver name.

Parameters
aDriverName	The name of the physical device driver object. This must match the name set during installation of the physical device. Typically, this is done in an implementation of DPhysicalDevice::Install() through a call to SetName(). Note that the name is rarely the same as the device's filename. The name of a physical device driver object can be discovered by using TFindPhysicalDevice.

Return Value: KErrNone if successful or one of the system-wide error codes. KErrNone will be returned if the device is not found as it may have already been freed.

FreeZ ( TAny *& )

IMPORT_C void

FreeZ

(

TAny *&

aCell

)

[static]

Frees the specified cell, returns it to the current thread's default heap, and resets the pointer to NULL.

Parameters
aCell	A reference to a pointer to a valid cell to be freed. If NULL this function call will be ignored.

Panic Codes
USER	42, if aCell is not NULL and does not point to a valid cell.

GetDesParameter ( TInt, TDes8 & )

IMPORT_C TInt	GetDesParameter	(	TInt	aSlot,
			TDes8 &	aDes
		)	[static]

Gets the specified environment data item belonging to the current process; this is assumed to be an 8-bit descriptor.

Environment data may be stored in the process and is passed to a child process on creation of that child process.

On successful return from this function, the data item is deleted from the process.

Parameters
aSlot	An index that identifies the data item. This is an index whose value is relative to zero; i.e. 0 is the first item/slot. This can range from 0 to 15, i.e. there are 16 slots.
aDes	On sucessful return, contains the environment data item; the length of the descriptor is set to the length of the data item.

Return Value: KErrNone, if successful; KErrNotFound, if there is no data; KErrArgument, if the data is not binary data, or the data item in the process is longer than the maximum length of aDes.

Panic Codes
KERN-EXEC	51, if aSlot is negative or is greater than or equal to 16.

GetDesParameter ( TInt, TDes16 & )

IMPORT_C TInt	GetDesParameter	(	TInt	aSlot,
			TDes16 &	aDes
		)	[static]

Gets the specified environment data item belonging to the current process; this is assumed to be an 16-bit descriptor.

Environment data may be stored in the process and is passed to a child process on creation of that child process.

On successful return from this function, the data item is deleted from the process.

Parameters
aSlot	An index that identifies the data item. This is an index whose value is relative to zero; i.e. 0 is the first item/slot. This can range from 0 to 15, i.e. there are 16 slots.
aDes	On sucessful return, contains the environment data item; the length of the descriptor is set to the length of the data item.

Return Value: KErrNone, if successful; KErrNotFound, if there is no data; KErrArgument, if the data is not binary data, or the data item in the process is longer than the maximum length of aDes.

Panic Codes
KERN-EXEC	51, if aSlot is negative or is greater than or equal to 16.

GetGlobalData ( TGlobalDataType, TUint & )

IMPORT_C TInt	GetGlobalData	(	TGlobalDataType	aType,
			TUint &	aData
		)	[static]

Get the global data entry specified by aType.

Parameters
aType	The global data entry to be set.
aData	This will hold the global data value on successful return from this method.

Return Value: KErrNone on success, KErrNotSupported if the device doesn't support global data, KErrArgument if aType is invalid.

GetTIntParameter ( TInt, TInt & )

IMPORT_C TInt	GetTIntParameter	(	TInt	aSlot,
			TInt &	aData
		)	[static]

Gets the specified environment data item belonging to the current process; this is assumed to be a 32 bit value.

Environment data may be stored in the process and is passed to a child process on creation of that child process.

On successful return from this function, the data item is deleted from the process.

Parameters
aSlot	An index that identifies the data item. This is an index whose value is relative to zero; i.e. 0 is the first item/slot. This can range from 0 to 15, i.e. there are 16 slots.
aData	On sucessful return, contains the environment data item.

Return Value: KErrNone, if successful; KErrNotFound, if there is no data; KErrArgument, if the data is not binary data, or the data item in the process is longer than 32 bits.

Panic Codes
KERN-EXEC	51, if aSlot is negative or is greater than or equal to 16.

HandleException ( TAny * )

IMPORT_C void

HandleException

(

TAny *

aInfo

)

[static]

Enables the current thread to handle an exception.

The function is called by the kernel.

Heap ( )

RHeap &

Heap

(

)

[static, inline]

Gets a reference to the handle to the current thread's heap.

Return Value: A reference to the handle to the current thread's heap.

IMB_Range ( TAny , TAny )

IMPORT_C void	IMB_Range	(	TAny *	aStart,
			TAny *	aEnd
		)	[static]

Does the necessary preparations to guarantee correct execution of code in the specified virtual address range.

The function assumes that this code has been loaded or modified by user code. Calling this function against uncommitted memory region is considered as S/W bug and may generate exception on some memory models.

The specified addresses are associated with a user writable code chunk as created by RChunk::CreateLocalCode().

The function cleans the data cache to ensure that written data has been committed to main memory and then flushes the instruction cache and branch target buffer (BTB) to ensure that the code is loaded from main memory when it is executed. The Kernel uses the size of the range specified to decide whether to clean/flush line-by-line or to simply clean/flush the entire cache.

Parameters
aStart	The start virtual address of the region.
aEnd	The end virtual address of the region. This location is not within the region.

Identity ( )

TUid

Identity

(

)

[static, inline]

InactivityTime ( )

IMPORT_C TTimeIntervalSeconds

InactivityTime

(

)

[static]

Gets the time since the last user activity.

Return Value: The time interval.

InfoPrint ( const TDesC & )

IMPORT_C TInt

InfoPrint

(

const TDesC &

aDes

)

[static]

Invokes the notifier server to display a text message on the screen for a short time.

InitProcess ( )

IMPORT_C void

InitProcess

(

)

[static]

Invariant ( )

IMPORT_C void

Invariant

(

)

[static]

Panics the current thread with a USER 0 panic.

Typically, this is called when a test for a class invariant fails, i.e. when a test which checks that the internal data of an object is self-consistent, fails.

Such tests are almost always done in debug builds, commonly using the __ASSERT_DEBUG macro.

IsExceptionHandled ( TExcType )

IMPORT_C TBool

IsExceptionHandled

(

TExcType

aType

)

[static]

Tests whether the specified exception type can be handled by the current thread.

Parameters
aType	The type of exception.

Return Value: True, if the thread has an exception handler which can handle an exception of type aType. False, if the thread has no exception handler or the thread has an exception handler which cannot handle the exception defined by aType.

IsRomAddress ( TBool &, TAny * )

IMPORT_C TInt	IsRomAddress	(	TBool &	aBool,
			TAny *	aPtr
		)	[static]

Tests whether the specified address is in the ROM.

Parameters
aBool	True, if the address at aPtr is within the ROM; false, otherwise.
aPtr	The address to be tested.

Return Value: Always KErrNone.

JustInTime ( )

IMPORT_C TBool

JustInTime

(

)

[static]

Tests whether just-in-time debugging is on or off.

The function is used by the Kernel, on the Emulator, to decide whether to do just-in-time debugging for panics. The function applies to the current process.

Unless overridden by calling User::SetJustInTime(EFalse), just-in-time debugging is on by default.

Language ( )

IMPORT_C TLanguage

Language

(

)

[static]

Gets the language of the current locale.

Return Value: One of the TLanguage enumerators identifying the language of the current locale.

Leave ( TInt )

IMPORT_C void

Leave

(

aReason

)

[static]

Leaves the currently executing function, unwinds the call stack, and returns from the most recently entered trap harness.

See also: TRAP TRAPD

Parameters
aReason	The value returned from the most recent call to TRAP or TRAPD. This is known as the reason code and, typically, it gives the reason for the environment or user error causing this leave to occur.

LeaveEnd ( )

IMPORT_C void

LeaveEnd

(

)

[static]

LeaveIfError ( TInt )

IMPORT_C TInt

LeaveIfError

(

aReason

)

[static]

Leaves or returns with a specified reason code.

If the reason code is negative the function leaves, and the reason code is returned through the trap harness.

If the reason code is zero or positive, the function simply returns with the reason value.

Parameters
aReason	The reason code.

Return Value: If the function returns, the reason code which is either zero or positive.

LeaveIfNull ( TAny * )

IMPORT_C TAny *

LeaveIfNull

(

TAny *

aPtr

)

[static]

Leaves with the reason code KErrNoMemory, if the specified pointer is NULL.

If the pointer is not NULL, the function simply returns with the value of the pointer.

Parameters
aPtr	The pointer to be tested.

Return Value: If the function returns, the value of aPtr.

LeaveIfNull ( const TAny * )

const TAny *

LeaveIfNull

(

const TAny *

aPtr

)

[static, inline]

Leaves with the reason code KErrNoMemory, if the specified pointer is NULL.

If the pointer is not NULL, the function simply returns with the value of the pointer.

Used to check pointers to const objects.

Parameters
aPtr	The pointer to be tested.

Return Value: If the function returns, the value of aPtr.

LeaveNoMemory ( )

IMPORT_C void

LeaveNoMemory

(

)

[static]

Leaves with the specific reason code KErrNoMemory.

LoadLogicalDevice ( const TDesC & )

IMPORT_C TInt

LoadLogicalDevice

(

const TDesC &

aFileName

)

[static]

Loads the logical device driver (LDD) DLL with the specified filename.

The function searches the system path for the LDD DLL, and loads it. It then makes a kernel server call that:

1. creates the LDD factory object, an instance of a DLogicalDevice derived class; this involves checking the first UID value to make sure that the DLL is a valid LDD before proceeding to call the exported function at ordinal 1, which creates the LDD factory object on the kernel heap

2. calls the LDD factory object's Install() function to complete the installation

3. adds the new LDD factory object to the kernel's list of LDD factory objects.

Parameters
aFileName	A reference to the descriptor containing the name of the physical device driver DLL. If the filename has no extension, .LDD is assumed by default.

Return Value: KErrNone if successful or one of the system-wide error codes.

LoadPhysicalDevice ( const TDesC & )

IMPORT_C TInt

LoadPhysicalDevice

(

const TDesC &

aFileName

)

[static]

Loads the physical device driver (PDD) DLL with the specified filename.

The function searches the system path for the PDD DLL, and loads it. It then makes a kernel server call that:

1. creates the PDD factory object, an instance of a DPhysicalDevice derived class; this involves checking the first UID value to make sure that the DLL is a valid PDD before proceeding to call the exported function at ordinal 1, which creates the PDD factory object on the kernel heap

2. calls the PDD factory object's Install() function to complete the installation

2. adds the new PDD factory object to the kernel's list of PDD factory objects.

Parameters
aFileName	A reference to the descriptor containing the name of the physical device driver DLL. If the filename has no extension, .PDD is assumed by default.

Return Value: KErrNone if successful or one of the system-wide error codes.

LockPeriod ( )

IMPORT_C TTimerLockSpec

LockPeriod

(

)

[static]

Returns which of the periods the clock is currently in.

Return Value: The fraction of a second at which the timer completes.

LockedDec ( TInt & )

IMPORT_C TInt

LockedDec

(

TInt &

aValue

)

[static]

Atomically (i.e. in a manner which is safe against concurrent access by other threads) decrements a TInt value by 1.

As an example of its use, the function is used in the implementation of critical sections.

See also: User::LockedInc RCrticalSection

Parameters
aValue	A reference to an integer whose value is to be decremented. On return contains the decremented value.

Return Value: The value of aValue before it is decremented.

LockedInc ( TInt & )

IMPORT_C TInt

LockedInc

(

TInt &

aValue

)

[static]

Atomically (i.e. in a manner which is safe against concurrent access by other threads) increments a TInt value by 1.

As an example of its use, the function is used in the implementation of critical sections.

See also: User::LockedDec RCrticalSection

Parameters
aValue	A reference to an integer whose value is to be incremented. On return contains the incremented value.

Return Value: The value of aValue before it is incremented.

LowerCase ( TUint )

IMPORT_C TUint

LowerCase

(

aChar

)

[static]

Converts the specified character to lower case.

The result of the conversion depends on the locale and on whether this is a UNICODE build or not.

Note that for a non-UNICODE build, if the binary value of the character aChar is greater than or equal to 0x100, then the character returned is the same as the character passed to the function.

Parameters
aChar	The character to be converted to lower case.

Return Value: The lower case character.

MachineConfiguration ( TDes8 &, TInt & )

IMPORT_C TInt	MachineConfiguration	(	TDes8 &	aConfig,
			TInt &	aSize
		)	[static]

Gets the machine configuration.

Parameters
aConfig	On return contains the machine configuration data.
aSize	On return, contains the size of the data.

Return Value: KErrNone, if sucessful, otherwise one of the other system-wide error codes.

Capability
ReadDeviceData

MarkCleanupStack ( )

IMPORT_C TTrapHandler *

MarkCleanupStack

(

)

[static]

If there's a TTrapHandler installed marks the cleanup stack and returns the TTrapHandler for subsequent use in UnMarkCleanupStack.

Only intended for use in the defintion of TRAP and TRAPD and only when User::Leave is defined in terms of THROW.

See also: TRAP TRAPD

Return Value: A pointer to the current thread's pre-existing trap handler, if any. NULL, if no pre-existing trap handler is set.

ModifyExceptionMask ( TUint32, TUint32 )

IMPORT_C void	ModifyExceptionMask	(	TUint32	aClearMask,
			TUint32	aSetMask
		)	[static]

Changes the set of exceptions which the current thread's exception handler can deal with.

aClearMask is the set of flags defining the set of exceptions which the exception handler no longer deals with, while aSetMask is the set of flags defining the new set of exceptions to be set.

Flag clearing is done before flag setting.

Parameters
aClearMask	One or more flags defining the exceptions which the current exception handler no longer deals with.
aSetMask	One or more flags defining the new set of exceptions which the current exception handler is to deal with.

NTickCount ( )

IMPORT_C TUint32

NTickCount

(

)

[static]

Gets the nanokernel tick count.

This is the current value of the machine's millisecond tick counter.

On the emulator the resolution defaults to 5 milliseconds; however you can change it to N milliseconds when you launch the emulator from the command line by specifying -Dtimerresolution=N as a parameter to epoc.exe, for example:

epoc.exe -Dtimerresolution=3

On most hardware the resolution is about 1 millisecond.

You can get the nanokernel tick period in microseconds by calling into the Hardware Abstraction Layer:

TInt nanokernel_tick_period;
HAL::Get(HAL::ENanoTickPeriod, nanokernel_tick_period);

Return Value: The nanokernel tick count.

NotifyOnIdle ( TRequestStatus & )

IMPORT_C void

NotifyOnIdle

(

TRequestStatus &

aStatus

)

[static]

Queue a notifier to detect system idle

Panic ( const TDesC &, TInt )

IMPORT_C void	Panic	(	const TDesC &	aCategory,
			TInt	aReason
		)	[static]

Panics the current thread, specifying a category name and panic number.

Keep the length of the category name small; it is limited to 16 characters.

Parameters
aCategory	A reference to the descriptor containing the text that defines the category for this panic.
aReason	The panic number.

PanicAbsentOrdinalCalled ( )

IMPORT_C void

PanicAbsentOrdinalCalled

(

)

[static]

PanicUnexpectedLeave ( )

IMPORT_C void

PanicUnexpectedLeave

(

)

[static]

ParameterLength ( TInt )

IMPORT_C TInt

ParameterLength

(

aSlot

)

[static]

Gets the length of the specified item of environment data belonging to the current process.

Environment data may be stored in the process and is passed to a child process on creation of that child process.

Parameters
aSlot	An index that identifies the data item whose length is to be retrieved. This is an index whose value is relative to zero; i.e. 0 is the first item/slot. This can range from 0 to 15, i.e. there are 16 slots.

Return Value: KErrNotFound, if there is no data; KErrArgument, if the data is not binary data; The length of the data item.

Panic Codes
KERN-EXEC	51, if aSlot is negative or is greater than or equal to 16.

PriorityControl ( )

IMPORT_C TBool

PriorityControl

(

)

[static]

Tests whether the current process allows other processes to switch its priority between 'foreground' and 'background'.

Return Value: True, if the current process allows other processes to switch its priority; false, otherwise.

ProcessCritical ( )

IMPORT_C TCritical

ProcessCritical

(

)

[static]

Gets the critical state associated with the current process.

ProcessCritical ( RProcess )

IMPORT_C TCritical

ProcessCritical

(

RProcess

aProcess

)

[static]

Gets the critical state associated with the specified process.

QueryVersionSupported ( const TVersion &, const TVersion & )

IMPORT_C TBool	QueryVersionSupported	(	const TVersion &	aCurrent,
			const TVersion &	aRequested
		)	[static]

Compares two version objects and returns true if the test version is less than the current version.

Version information is encapsulated by a TVersion type object and consists of a major version number, a minor version number and a build number.

The function returns true if one of the following conditions is true:

1. the test major version is strictly less than the current major version

2. the test major version is equal to the current major version and the test minor version is less than or equal to the current minor version

If neither condition is true, the function returns false.

Parameters
aCurrent	A reference to the current version against which aRequested is compared.
aRequested	A reference to the test version to be compared against aCurrent.

Return Value: True, if one or both conditions are true. False otherwise.

QuickSort ( TInt, const TKey &, const TSwap & )

IMPORT_C TInt	QuickSort	(	TInt	aCount,
			const TKey &	aKey,
			const TSwap &	aSwap
		)	[static]

Quick sorts array elements.

It is used by the standard Symbian OS arrays having CArrayFixBase, CArrayVarBase or CArrayPakBase in their class hierarchy in the implementation of their sort functions. The function can be used by other arrays.

The function returns KErrNone if the operation is successful otherwise it returns KErrGeneral.

Parameters
aCount	The number of elements in the array.
aKey	A reference to a suitably initialised TKey derived object.
aSwap	A reference to a suitably initialised TSwap derived object.

Return Value: KErrNone if the operation is successful; KErrGeneral otherwise.

Panic Codes
USER	96, if aCount is negative.

RaiseException ( TExcType )

IMPORT_C TInt

RaiseException

(

TExcType

aType

)

[static]

Raises an exception of a specified type on the current thread.

If the thread has an exception handler to handle this type of exception, then it is called.

If the thread has no exception handler to handle this type of exception, then the function raises a USER-EXEC 3 panic.

Note that exception handlers are executed in the context of the thread on which the exception is raised; control returns to the point of the exception.

Parameters
aType	The type of exception.

Return Value: KErrNone if successful, otherwise another of the system-wide error codes.

ReAlloc ( TAny *, TInt, TInt )

IMPORT_C TAny *	ReAlloc	(	TAny *	aCell,
			TInt	aSize,
			TInt	aMode = 0
		)	[static]

Increases or decreases the size of an existing cell in the current thread's heap.

If the cell is being decreased in size, then it is guaranteed not to move, and the function returns the pointer originally passed in aCell. Note that the length of the cell will be the same if the difference between the old size and the new size is smaller than the minimum cell size.

If the cell is being increased in size, i.e. aSize is bigger than its current size, then the function tries to grow the cell in place. If successful, then the function returns the pointer originally passed in aCell. If unsuccessful, then:

if the cell cannot be moved, i.e. aMode has the ENeverMove bit set, then the function returns NULL.
if the cell can be moved, i.e. aMode does not have the ENeverMove bit set, then the function tries to allocate a new replacement cell, and, if successful, returns a pointer to the new cell; if unsuccessful, it returns NULL.

Note that in debug mode, the function returns NULL if the cell cannot be grown in place, regardless of whether the ENeverMove bit is set.

If the reallocated cell is at a different location from the original cell, then the content of the original cell is copied to the reallocated cell.

If the supplied pointer, aCell is NULL, then the function attempts to allocate a new cell, but only if the cell can be moved, i.e. aMode does not have the ENeverMove bit set.

Note the following general points:

If reallocation fails, the content of the original cell is preserved.
The resulting size of the re-allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

ReAllocL ( TAny *, TInt, TInt )

IMPORT_C TAny *	ReAllocL	(	TAny *	aCell,
			TInt	aSize,
			TInt	aMode = 0
		)	[static]

Increases or decreases the size of an existing cell, and leaves if there is insufficient memory in the current thread's default heap.

if the cell cannot be moved, i.e. aMode has the ENeverMove bit set, then the function leaves.
if the cell can be moved, i.e. aMode does not have the ENeverMove bit set, then the function tries to allocate a new replacement cell, and, if successful, returns a pointer to the new cell; if unsuccessful, it leaves.

Note that in debug mode, the function leaves if the cell cannot be grown in place, regardless of whether the ENeverMove bit is set.

If the reallocated cell is at a different location from the original cell, then the content of the original cell is copied to the reallocated cell.

If the supplied pointer, aCell is NULL, then the function attempts to allocate a new cell, but only if the cell can be moved, i.e. aMode does not have the ENeverMove bit set.

Note the following general points:

If reallocation fails, the content of the original cell is preserved.
The resulting size of the re-allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

RegionCode ( )

IMPORT_C TRegionCode

RegionCode

(

)

[static]

RenameProcess ( const TDesC & )

IMPORT_C TInt

RenameProcess

(

const TDesC &

aName

)

[static]

Assigns a new name to the current process, replacing any existing name.

When a process is created, its default name is the name portion of the filename from which the executable is loaded.

The new name must be a valid name and it must also be such that the process's new fullname remains unique amongst processes.

Parameters
aName	A reference to the descriptor containing the new name of the process.

Return Value: KErrNone, if successful, or if the new and old names are identical; KErrBadName, if aName is an invalid; otherwise one of the other system-wide error codes.

RenameThread ( const TDesC & )

IMPORT_C TInt

RenameThread

(

const TDesC &

aName

)

[static]

Assigns a new name to the current thread, replacing any existing name that may have been set.

The new name must be a valid name and it must also be such that the thread's new fullname remains unique amongst threads. The length of the new name must be less than or equal to 80 (maximum length of kernel objects) otherwise a panic is raised.

Parameters
aName	A reference to the descriptor containing the new name for the thread.

Return Value: KErrNone if successful, otherwise one of the other system-wide error codes.

RequestComplete ( TRequestStatus *&, TInt )

IMPORT_C void	RequestComplete	(	TRequestStatus *&	aStatus,
			TInt	aReason
		)	[static]

Signals the current thread that the asynchronous request associated with the specified request status object is complete.

This function is used to complete an asynchronous request originating in the same thread as the code that is currently executing. If a request originates in another thread, then executing code must use RThread::RequestComplete() to signal the completion of that request.

The request is completed with the completion code passed in aReason. This value is copied into the request status, pointed to by aStatus, before signalling the current thread's request semaphore.

The meaning of the completion code passed in aReason is a matter of convention to be decided between the service requester and the service provider.

ResetInactivityTime ( )

IMPORT_C void

ResetInactivityTime

(

)

[static]

Resets all user inactivity timers.

SafeDec ( TInt & )

IMPORT_C TInt

SafeDec

(

TInt &

aValue

)

[static]

Atomically decrements the specified value by 1, if the value is > 0.

Parameters
aValue	The value to be decremented; on return the decremented value.

Return Value: The original value of aValue

SafeInc ( TInt & )

IMPORT_C TInt

SafeInc

(

TInt &

aValue

)

[static]

Atomically increments the specified value by 1, if the value is > 0.

Parameters
aValue	The value to be incremented; on return the incremented value.

Return Value: The original value of aValue

SetCritical ( TCritical )

IMPORT_C TInt

SetCritical

(

TCritical

aCritical

)

[static]

Sets up or changes the effect that termination of the current thread has, either on its owning process, or on the whole system.

The precise effect of thread termination is defined by the following specific values of the TCritical enum:

ENotCritical
EProcessCritical
EProcessPermanent
ESystemCritical
ESystemPermanent

Notes:

The enum value EAllThreadsCritical cannot be set using this function. It is associated with a process, not a thread, and, if appropriate, should be set using User::SetProcessCritical().
The states associated with ENotCritical, EProcessCritical, EProcessPermanent, ESystemCritical and ESystemPermanent are all mutually exclusive, i.e. the thread can only be in one of these states at any one time

Parameters
aCritical	The state to be set.

Return Value: KErrNone, if successful; KErrArgument, if EAllThreadsCritical is passed - this is a state associated with a process, and you use User::SetProcessCritical() to set it.

Capability
ProtServ	if aCritical==ESystemCritical or ESystemPermanent

SetCurrencySymbol ( const TDesC & )

IMPORT_C TInt

SetCurrencySymbol

(

const TDesC &

aSymbol

)

[static]

Sets the system wide currency symbol.

On successful return from this function, a call to the Set() member function of a TCurrencySymbol object fetches the new currency symbol.

Parameters
aSymbol	A reference to the descriptor containing the currency symbol to be set.

Return Value: KErrNone if successful, otherwise one of the other system wide error codes.

Panic Codes
USER	119, if the length of aSymbol is greater than KMaxCurrencySymbol.

Capability
WriteDeviceData

SetDebugMask ( TUint32 )

IMPORT_C void

SetDebugMask

(

TUint32

aVal

)

[static]

Sets the debug mask.

Parameters
aVal	A set of bit values as defined in nk_trace.h

SetDebugMask ( TUint32, TUint )

IMPORT_C void	SetDebugMask	(	TUint32	aVal,
			TUint	aIndex
		)	[static]

Sets the debug mask at the given index

Parameters
aVal	A set of bit values as defined in nk_trace.h
aIndex	An index of which 32 bit mask word is to be accessed

SetExceptionHandler ( TExceptionHandler, TUint32 )

IMPORT_C TInt	SetExceptionHandler	(	TExceptionHandler	aHandler,
			TUint32	aMask
		)	[static]

Sets a new exception handler for the current thread. Note that the handler is not guaranteed to receive floating point exceptions (KExceptionFpe) when a hardware floating point implementation is in use - see User::SetFloatingPointMode for hardware floating point modes and whether they cause user-trappable exceptions.

Parameters
aHandler	The new exception handler.
aMask	One or more flags defining the exception categories which the handler can handle.

Return Value: KErrNone if successful, otherwise another of the system-wide error codes.

SetFloatingPointMode ( TFloatingPointMode, TFloatingPointRoundingMode )

IMPORT_C TInt	SetFloatingPointMode	(	TFloatingPointMode	aMode,
			TFloatingPointRoundingMode	aRoundingMode = EFpRoundToNearest
		)	[static]

Sets the hardware floating point mode for the current thread. This does not affect software floating point calculations. The rounding mode can also be set. New threads created by this thread will inherit the mode, thus to set the mode for a whole process, call this method before you create any new threads.

Parameters
aMode	The floating point calculation mode to use.
aRoundingMode	The floating point rounding mode to use, defaults to nearest.

Return Value: KErrNone if successful, KErrNotSupported if the hardware does not support the chosen mode, or there is no floating point hardware present.

SetHomeTime ( const TTime & )

IMPORT_C TInt

SetHomeTime

(

const TTime &

aTime

)

[static]

Sets the home time to a specified time value.

DeprecatedSet the time using User::SetUTCTime if the UTC time is known; otherwise, use the timezone server to set the time.

Parameters
aTime	A reference to a time representation object containing the time value.

Return Value: KErrNone if successful or one of the system-wide error codes.

Capability
WriteDeviceData

SetHomeTimeSecure ( const TTime & )

IMPORT_C TInt

SetHomeTimeSecure

(

const TTime &

aTime

)

[static]

Sets the secure home time to a specified time value.

Parameters
aTime	A reference to a time representation object containing the secure time value.

Return Value: KErrNone if successful or one of the system-wide error codes.

Capability
TCB
WriteDeviceData

SetJustInTime ( const TBool )

IMPORT_C void

SetJustInTime

(

const TBool

aBoolean

)

[static]

Sets just-in-time debugging for this process on or off.

While the function can be called by code running on both the Emulator and ARM, it only has an effect on the Emulator. Turning just-in-time debugging off prevents the debug Emulator closing down when a panic occurs.

By default, just-in-time debugging is on.

Note that the emulator handles panics in the nomal manner, i.e. by killing the thread.

SetMachineConfiguration ( const TDesC8 & )

IMPORT_C TInt

SetMachineConfiguration

(

const TDesC8 &

aConfig

)

[static]

Sets the machine configuration.

Parameters
aConfig	Descriptor containing the machine configuration data

Return Value: KErrNone, if sucessful, otherwise one of the other system-wide error codes.

Capability
WriteDeviceData

SetPriorityControl ( TBool )

IMPORT_C void

SetPriorityControl

(

aEnable

)

[static]

Allows the current process to choose to have its priority switched by another process between 'foreground' and 'background'.

By default a process does not allow this.

Parameters
aEnable	If ETrue, allows other processes to switch the current process's priority. If EFalse, prevents other processes from switching the current process's priority.

SetProcessCritical ( TCritical )

IMPORT_C TInt

SetProcessCritical

(

TCritical

aCritical

)

[static]

Sets up or changes the effect that termination of subsequently created threads will have, either on the owning process, or on the whole system.

It is important to note that we are not referring to threads that have already been created, but threads that will be created subsequent to a call to this function.

The precise effect of thread termination is defined by the following specific values of the TCritical enum:

ENotCritical
EAllThreadsCritical
ESystemCritical
ESystemPermanent

Notes:

The enum values EProcessCritical and EProcessPermanent cannot be set using this function. They are states associated with a thread, not a process, and, if appropriate, should be set using User::SetCritical().
The states associated with ENotCritical, EAllThreadsCritical, ESystemCritical and ESystemPermanent are all mutually exclusive, i.e. the process can only be in one of these states at any one time.

Parameters
aCritical	The state to be set.

Return Value: KErrNone, if successful; KErrArgument, if either EProcessCritical or EProcessPermanent is passed - these are states associated with a thread, and you use User::SetCritical() to set them.

Capability
ProtServ	if aCritical==ESystemCritical or ESystemPermanent

SetRealtimeState ( TRealtimeState )

IMPORT_C TInt

SetRealtimeState

(

TRealtimeState

aState

)

[static]

Set the current threads realtime state.

SetTrapHandler ( TTrapHandler * )

IMPORT_C TTrapHandler *

SetTrapHandler

(

TTrapHandler *

aHandler

)

[static]

Sets the current thread's trap handler and returns a pointer to any pre-existing trap handler.

Pass a NULL pointer to this function to clear the trap handler.

The trap handler works with the TRAP mechanism to handle the effects of a leave.

Note that TTrapHandler is an abstract base class; a trap handler must be implemented as a derived class.

See also: TRAP TRAPD

Parameters
aHandler	A pointer to the trap handler which is to be installed as the current thread's trap handler.

Return Value: A pointer to the current thread's pre-existing trap handler, if any. NULL, if no pre-existing trap handler is set.

SetUTCOffset ( TTimeIntervalSeconds )

IMPORT_C void

SetUTCOffset

(

TTimeIntervalSeconds

aOffset

)

[static]

Sets the UTC offset to the given number of seconds. This should include both time zone differences and the effect of any applicable daylight savings time. A positive offset indicates a time ahead of UTC, a negative offset indicates a time behind UTC.

Parameters
aOffset	The UTC offset, in seconds.

Capability
WriteDeviceData

SetUTCTime ( const TTime & )

IMPORT_C TInt

SetUTCTime

(

const TTime &

aUTCTime

)

[static]

Sets the UTC time to a specified time value.

Parameters
aUTCTime	A reference to a time representation object containing the time value.

Return Value: KErrNone if successful or one of the system-wide error codes.

Capability
WriteDeviceData

SetUTCTimeAndOffset ( const TTime &, TTimeIntervalSeconds )

IMPORT_C TInt	SetUTCTimeAndOffset	(	const TTime &	aUTCTime,
			TTimeIntervalSeconds	aOffset
		)	[static]

Sets the UTC time and UTC offset to the specified values, atomically. This is equivalent to calling both SetUTCTime and SetUTCOffset, but without the possibility of an incorrect time being observed between the two calls. If the operation is not successful, an error code will be returned and both the time and offset will be left unchanged.

Parameters
aUTCTime	A reference to a time representation object containing the time value.
aOffset	The UTC offset, in seconds.

Return Value: KErrNone if successful or one of the system-wide error codes.

Capability
WriteDeviceData

SetUTCTimeSecure ( const TTime & )

IMPORT_C TInt

SetUTCTimeSecure

(

const TTime &

aUTCTime

)

[static]

Sets the secure UTC time to a specified time value.

Parameters
aUTCTime	A reference to a time representation object containing the secure time value.

Return Value: KErrNone if successful or one of the system-wide error codes.

Capability
TCB
WriteDeviceData

StringLength ( const TUint8 * )

IMPORT_C TInt

StringLength

(

const TUint8 *

aString

)

[static]

Gets the length of a C style, null terminated, string of single-byte valued characters.

The length does not include the null terminator.

Parameters
aString	A pointer to the single byte valued, null terminated, string.

Return Value: The length of the string.

StringLength ( const TUint16 * )

IMPORT_C TInt

StringLength

(

const TUint16 *

aString

)

[static]

Gets the length of a C style, null terminated, string of double-byte valued characters.

The length does not include the null terminator.

Parameters
aString	A pointer to the double-byte valued, null terminated, string.

Return Value: The length of the string.

SwitchAllocator ( RAllocator * )

IMPORT_C RAllocator *

SwitchAllocator

(

RAllocator *

aAllocator

)

[static]

Changes the current thread's heap.

Parameters
aAllocator	A pointer to the new heap handle.

Return Value: A pointer to the old heap handle.

SwitchHeap ( RAllocator * )

RHeap *

SwitchHeap

(

RAllocator *

aHeap

)

[static, inline]

Changes the current thread's heap.

Parameters
aHeap	A pointer to the new heap handle.

Return Value: A pointer to the old heap handle.

TickCount ( )

IMPORT_C TUint

TickCount

(

)

[static]

Gets the current tick count.

The period between ticks is usually 1/64 second, but may be hardware dependent.

Return Value: The machine dependent tick count.

TitleCase ( TUint )

IMPORT_C TUint

TitleCase

(

aChar

)

[static]

Converts a specified character to its title case version.

Parameters
aChar	The character to be converted.

Return Value: The converted character.

TrapHandler ( )

IMPORT_C TTrapHandler *

TrapHandler

(

)

[static]

Gets a pointer to the current thread's trap handler.

Note that TTrapHandler is an abstract base class; a trap handler must be implemented as a derived class.

Return Value: A pointer to the current thread's trap handler, if any. NULL, if no pre-existing trap handler is set.

UTCOffset ( )

IMPORT_C TTimeIntervalSeconds

UTCOffset

(

)

[static]

Gets the UTC offset - the difference between UTC and the current local time due to any time zones and daylight savings time that may be in effect. A positive offset indicates a time ahead of UTC, a negative offset indicates a time behind UTC.

Return Value: The UTC offset, in seconds.

UnMarkCleanupStack ( TTrapHandler * )

IMPORT_C void

UnMarkCleanupStack

(

TTrapHandler *

aHandler

)

[static]

If passed a non-null TTrapHandler unmarks the cleanup stack.

Only intended for use in the defintion of TRAP and TRAPD and only when User::Leave is defined in terms of THROW.

See also: TRAP TRAPD

UpperCase ( TUint )

IMPORT_C TUint

UpperCase

(

aChar

)

[static]

Converts a specified character to upper case.

The result of the conversion depends on the locale and on whether this is a UNICODE build or not.

Note that for a non UNICODE build, if the binary value of the character aChar is greater than or equal to 0x100, then the character returned is the same as the character passed to the function.

Parameters
aChar	The character to be converted to upper case.

Return Value: The upper case character.

ValidateName ( const TDesC & )

IMPORT_C TInt

ValidateName

(

const TDesC &

aName

)

[static]

Checks whether a specified name is a valid CObject name.

A name is deemed to be invalid, if it contains any of the characters: "*", "?", ":" i.e. the characters: asterisk, question mark and single colon.

Version ( )

IMPORT_C TVersion

Version

(

)

[static]

Retrieves the E32 component version number, which is the kernel architecture version number. For example for EKA2 the major part of the version number will be 2.

Return Value: The E32 component version number.

WaitForAnyRequest ( )

IMPORT_C void

WaitForAnyRequest

(

)

[static]

Waits for any asynchronous request to complete.

The current thread waits on its request semaphore.

The function completes, and control returns to the caller when the current thread's request semaphore is signalled by any of the service providers which handle these asynchronous requests.

The request status of all outstanding asynchronous requests must be examined to determine which request is complete.

WaitForNRequest ( TRequestStatus *, TInt )

IMPORT_C void	WaitForNRequest	(	TRequestStatus *	aStatusArray,
			TInt	aNum
		)	[static]

Waits for any one of specific asynchronous requests to complete.

The current thread waits on its request semaphore.

The function completes and control returns to the caller when the current thread's request semaphore is signalled by the service provider handling the request associated with any member of aStatusArray[]. Before signalling, the completing service provider sets an appropriate value in the status object, other than KRequestPending.

Note that if other asynchronous requests complete before the ones associated with aStatusArray the request semaphore is adjusted so that knowledge of their completion is not lost. In this a case, a subsequent call to User::WaitForAnyRequest() or User::WaitForRequest() will complete and return immediately.

WaitForRequest ( TRequestStatus & )

IMPORT_C void

WaitForRequest

(

TRequestStatus &

aStatus

)

[static]

Waits for a specific asynchronous request to complete.

The current thread waits on its request semaphore.

The function completes and control returns to the caller when the current thread's request semaphore is signalled by the service provider handling the request associated with aStatus. Before signalling, the service provider sets an appropriate value in aStatus, other than KRequestPending.

Note that if other asynchronous requests complete before the one associated with aStatus, the request semaphore is adjusted so that knowledge of their completion is not lost. In this a case, a subsequent call to User::WaitForAnyRequest() or User::WaitForRequest() will complete and return immediately.

WaitForRequest ( TRequestStatus &, TRequestStatus & )

IMPORT_C void	WaitForRequest	(	TRequestStatus &	aStatus1,
			TRequestStatus &	aStatus2
		)	[static]

Waits for either of two specific asynchronous requests to complete.

The current thread waits on its request semaphore.

The function completes and control returns to the caller when the current thread's request semaphore is signalled by either the service provider handling the request associated with aStatus1 or the service provider handling the request associated with aStatus2. Before signalling, the completing service provider sets an appropriate value in the status object, other than KRequestPending.

Note that if other asynchronous requests complete before the ones associated with aStatus1 and aStatus2, the request semaphore is adjusted so that knowledge of their completion is not lost. In this a case, a subsequent call to User::WaitForAnyRequest() or User::WaitForRequest() will complete and return immediately.

__DbgCheckFailure ( TBool )

IMPORT_C TUint

__DbgCheckFailure

(

aKernel

)

[static]

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.

__DbgGetAllocFail ( TBool )

IMPORT_C RAllocator::TAllocFail

__DbgGetAllocFail

(

aKernel

)

[static]

After calling __DbgSetAllocFail(), this function may be called to retrieve the value set. This is useful primarily for test code that doesn't know if a heap has been set to fail and needs to check.

Parameters
aKernel	ETrue, if checking is being done for the kernel heap; EFalse, if checking is being done for the current thread's default heap.

Return Value: RAllocator::ENone if heap is not in failure simulation mode; Otherwise one of the other RAllocator::TAllocFail enumerations

__DbgMarkCheck ( TBool, TBool, TInt, const TUint8 *, TInt )

IMPORT_C void	__DbgMarkCheck	(	TBool	aKernel,
			TBool	aCountAll,
			TInt	aCount,
			const TUint8 *	aFileName,
			TInt	aLineNum
		)	[static]

Checks the current number of allocated heap cells for the current thread's default heap, or the kernel heap.

If aCountAll is true, the function checks that the total number of allocated cells on the heap is the same as aCount. If aCountAll is false, the function checks that the number of allocated cells at the current nested level is the same as aCount.

If checking fails for a user heap, the function raises a panic. Information about the failure is put into the panic category, which takes the form:

ALLOC: aaaabbbb

Where aaaa is the value aCount and bbbb is the number of allocated heap cells. Both values are in hexadecimal format. The panic number is 1.

If the check fails for the kernel heap, the kernel server raises a KERN-EXEC 17 panic.

Parameters
aKernel	ETrue, if checking is being done for the kernel heap; EFalse, if checking is being done for the current thread's default heap.
aCountAll	If true, the function checks that the total number of allocated cells on the heap is the same as aCount. If false, the function checks that the number of allocated cells at the current nested level is the same as aCount.
aCount	The expected number of allocated cells.
aFileName	A filename; this is not used
aLineNum	A line number; this is not used

__DbgMarkEnd ( TBool, TInt )

IMPORT_C TUint32	__DbgMarkEnd	(	TBool	aKernel,
			TInt	aCount
		)	[static]

Marks the end of heap cell checking at the current nested level for the current thread's default heap, or the kernel heap.

The function checks that the number of heap cells allocated, at the current nested level, is aCount. The most common value for aCount is zero, reflecting the fact that the most common requirement is to check that all memory allocated since a previous call to __DbgStartCheck() has been freed.

A call to this function should match an earlier call to __DbgMarkStart().

If the check fails for a user heap, the function raises an ALLOC: nnnnnnnn panic, where nnnnnnnn is a hexadecimal pointer to the first orphaned heap cell. The panic number is 0.

If the check fails for the kernel heap, the kernel server raises a KERN-EXEC 17 panic.

Parameters
aKernel	ETrue, if checking is being done for the kernel heap; EFalse, if checking is being done for the current thread's default heap.
aCount	The number of allocated heap cells expected.

Return Value: Zero always.

__DbgMarkStart ( TBool )

IMPORT_C void

__DbgMarkStart

(