»
UIQ 3 SDK »
Symbian OS v9.1 »
Symbian OS reference »
C++ component reference »
Base E32 »
User
Location:
e32std.h
Link against: euser.lib
class User : public UserHeap;
Description
Set of static user functions.
These functions are related to a number of System component APIs.
The majority of the functions are related to either the current thread, or its heap. Examples in this category include User::Exit(), which causes the thread to terminate, and User::Alloc(), which allocates memory from the current thread's heap.
Some of these functions are equivalent to functions in the RThread or RHeap classes. In these cases, the User function is a convenient way to access the function without first having to get a handle to the current thread.
Functions are also provided to support debugging of memory leaks. These function calls can be written explicitly or can be generated using a corresponding macro - the advantage of using a macro is that the function call is only generated for debug builds.
A final category of functions, which includes User::BinarySearch() and User::QuickSort(), are just useful functions which have no other natural home.
Derivation
UserHeap - A set of static functions for constructing fixed length heaps and local or global heapsUser - Set of static user functions
Members
Defined in User:
After(), AfterHighRes(), Alloc(), AllocL(), AllocLC(), AllocLen(), AllocSize(), AllocZ(), AllocZL(), Allocator(), At(), Available(), Beep(), BinarySearch(), Check(), Collate(), CommandLine(), CommandLineLength(), CompressAllHeaps(), CountAllocCells(), CountAllocCells(), CreatorHasCapability(), CreatorHasCapability(), CreatorIdentity(), CreatorSecureId(), CreatorVendorId(), Critical(), Critical(), EAllThreadsCritical, ENotCritical, EProcessCritical, EProcessPermanent, ESystemCritical, ESystemPermanent, ExceptionHandler(), Exit(), FastCounter(), Fold(), Fold(), Free(), FreeLogicalDevice(), FreePhysicalDevice(), FreeZ(), GetDesParameter(), GetDesParameter(), GetTIntParameter(), Heap(), IMB_Range(), Identity(), InactivityTime(), InfoPrint(), Invariant(), IsExceptionHandled(), IsRomAddress(), JustInTime(), Language(), Leave(), LeaveIfError(), LeaveIfNull(), LeaveNoMemory(), LoadLogicalDevice(), LoadPhysicalDevice(), LockPeriod(), LockedDec(), LockedInc(), LowerCase(), MachineConfiguration(), ModifyExceptionMask(), NTickCount(), Panic(), ParameterLength(), PriorityControl(), ProcessCritical(), ProcessCritical(), QueryVersionSupported(), QuickSort(), RaiseException(), ReAlloc(), ReAllocL(), RenameProcess(), RenameThread(), RequestComplete(), ResetInactivityTime(), SafeDec(), SafeInc(), SetCritical(), SetCurrencySymbol(), SetDebugMask(), SetDebugMask(), SetExceptionHandler(), SetHomeTime(), SetJustInTime(), SetMachineConfiguration(), SetPriorityControl(), SetProcessCritical(), SetTrapHandler(), SetUTCOffset(), SetUTCTime(), SetUTCTimeAndOffset(), StringLength(), StringLength(), SwitchAllocator(), SwitchHeap(), TCritical, TickCount(), TitleCase(), TrapHandler(), UTCOffset(), UpperCase(), ValidateName(), Version(), WaitForAnyRequest(), WaitForRequest(), WaitForRequest(), __DbgMarkCheck(), __DbgMarkEnd(), __DbgMarkStart(), __DbgSetAllocFail()
Inherited from UserHeap:
ChunkHeap(),
EChunkHeapDuplicate,
EChunkHeapSwitchTo,
FixedHeap(),
TChunkHeapCreateMode
See also:
Member functions
static IMPORT_C void Exit(TInt aReason);
Description
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
TInt aReason |
The reason code. |
|
static IMPORT_C void Panic(const TDesC &aCategory, TInt aReason);
Description
Panics the current thread, specifying a category name and panic number.
Keep the length of the category name small; a length of 16 is ideal.
Parameters
const TDesC &aCategory |
A reference to the descriptor containing the text that defines the category for this panic. |
TInt aReason |
The panic number. |
|
static IMPORT_C void Leave(TInt aReason);
Description
Parameters
static IMPORT_C void LeaveNoMemory();
Description
Leaves with the specific reason code KErrNoMemory.
See also:
static IMPORT_C TInt LeaveIfError(TInt aReason);
Description
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
TInt aReason |
The reason code. |
|
Return value
TInt
|
If the function returns, the reason code which is either zero or positive. |
|
static IMPORT_C TAny *LeaveIfNull(TAny *aPtr);
Description
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
TAny *aPtr |
The pointer to be tested. |
|
Return value
TAny * |
If the function returns, the value of aPtr. |
|
static IMPORT_C TTrapHandler *SetTrapHandler(TTrapHandler *aHandler);
Description
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.
Parameters
TTrapHandler *aHandler |
A pointer to the trap handler which is to be installed as the current thread's trap handler. |
|
Return value
TTrapHandler * |
A pointer to the current thread's pre-existing trap handler, if any. NULL, if no pre-existing trap handler is set. |
|
See also:
static IMPORT_C TTrapHandler *TrapHandler();
Description
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
TTrapHandler * |
A pointer to the current thread's trap handler, if any. NULL, if no pre-existing trap handler is set. |
|
static IMPORT_C TInt InfoPrint(const TDesC &aDes);
Description
Invokes the notifier server to display a text message on the screen for a short time.
Parameters
const TDesC &aDes |
A reference to the descriptor containing the text to be sent to the notifier server. |
|
Return value
TInt
|
KErrNone if successful, otherwise one of the system-wide error codes. |
|
See also:
static IMPORT_C void RequestComplete(TRequestStatus *&aStatus, TInt aReason);
Description
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.
Parameters
TRequestStatus *&aStatus |
A reference to a pointer to the request status object. This is a pointer into the current thread's address space. On return, the pointer to the request status is set to NULL. Note that setting the pointer to NULL is a convenience, not all servers need it, and is done before the function returns. |
TInt aReason |
The completion code of this request. |
|
See also:
static IMPORT_C void WaitForAnyRequest();
Description
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.
See also:
static IMPORT_C void WaitForRequest(TRequestStatus &aStatus);
Description
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.
Parameters
TRequestStatus &aStatus |
A reference to the request status object associated with the specific asynchronous request. |
|
See also:
static IMPORT_C void WaitForRequest(TRequestStatus &aStatus1, TRequestStatus &aStatus2);
Description
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.
Parameters
TRequestStatus &aStatus1 |
A reference to the request status object associated with the first specific asynchronous request. |
TRequestStatus &aStatus2 |
A reference to the request status object associated with the second specific asynchronous request. |
|
See also:
static IMPORT_C TInt AllocLen(const TAny *aCell);
Description
Gets the length of the specified allocated heap cell.
The cell is assumed to be in the current thread's heap.
Parameters
const TAny *aCell |
A pointer to the allocated cell whose length is to be fetched. |
|
Return value
TInt
|
The length of the allocated cell. |
|
static IMPORT_C TAny *Alloc(TInt aSize);
Description
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
TInt aSize |
The size of the cell to be allocated from the current thread's heap. |
|
Return value
TAny * |
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. |
|
static IMPORT_C TAny *AllocL(TInt aSize);
Description
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
TInt aSize |
The size of the cell to be allocated from the current thread's heap. |
|
Return value
TAny * |
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. |
|
static IMPORT_C TAny *AllocLC(TInt aSize);
Description
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
TInt aSize |
The size of the cell to be allocated from the current thread's default heap. |
|
Return value
TAny * |
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. |
|
static IMPORT_C TAny *AllocZ(TInt aSize);
Description
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
TInt aSize |
The size of the cell to be allocated from the current thread's default heap. |
|
Return value
TAny * |
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. |
|
static IMPORT_C TAny *AllocZL(TInt aSize);
Description
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
TInt aSize |
The size of the cell to be allocated from the current thread's heap. |
|
Return value
TAny * |
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. |
|
static IMPORT_C TInt AllocSize(TInt &aTotalAllocSize);
Description
Gets the total number of cells allocated on the current thread's default heap, and the total space allocated to them.
Parameters
TInt &aTotalAllocSize |
On return, contains the total space allocated to the cells. |
|
Return value
TInt
|
The number of cells currently allocated on the current thread's heap. |
|
static IMPORT_C TInt Available(TInt &aBiggestBlock);
Description
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
TInt &aBiggestBlock |
On return, contains the space available in the largest free block on the current thread's default heap. |
|
Return value
TInt
|
The total free space currently available on the current thread's heap. |
|
static IMPORT_C TInt CountAllocCells();
Description
Gets the total number of cells allocated on the current thread's default heap.
Return value
TInt
|
The number of cells allocated on the current thread's default user heap. |
|
static IMPORT_C TInt CountAllocCells(TInt &aFreeCount);
Description
Gets the the total number of cells allocated, and the number of free cells, on the current thread's default heap.
Parameters
TInt &aFreeCount |
On return, contains the number of free cells on the current thread's default heap. |
|
Return value
TInt
|
The number of cells allocated on the current thread's default heap. |
|
static IMPORT_C void Free(TAny *aCell);
Description
Frees the specified cell and returns it to the current thread's default heap.
Parameters
TAny *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. |
|
static IMPORT_C void FreeZ(TAny *&aCell);
Description
Frees the specified cell, returns it to the current thread's default heap, and resets the pointer to NULL.
Parameters
TAny *&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. |
|
static IMPORT_C RAllocator &Allocator();
Description
Gets the current thread's default current heap.
Return value
static inline RHeap &Heap();
Description
Gets a reference to the handle to the current thread's heap.
Return value
RHeap & |
A reference to the handle to the current thread's heap. |
|
static IMPORT_C TAny *ReAlloc(TAny *aCell, TInt aSize, TInt aMode=0);
Description
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:
1. if the cell cannot be moved, i.e. aMode has the ENeverMove bit set, then the function returns NULL. 2. 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:
1. If reallocation fails, the content of the original cell is preserved.
2. 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.
Parameters
TAny *aCell |
A pointer to the cell to be reallocated. This may be NULL. |
TInt aSize |
The new size of the cell. This may be bigger or smaller than the size of the original cell. |
TInt aMode |
Flags controlling the reallocation. The only bit which has any effect on this function is that defined by the enumeration ENeverMove of the enum RAllocator::TReAllocMode. If this is set, then any successful reallocation guarantees not to have changed the start address of the cell. By default, this parameter is zero. |
|
Return value
TAny * |
A pointer to the reallocated cell. This may be the same as the original pointer supplied through aCell. NULL if there is insufficient memory to reallocate the cell, or to grow it in place. |
|
Panic codes
USER |
42, if aCell is not NULL, and does not point to a valid cell. |
USER |
47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling ReAlloc(someptr,-1) raises this panic. |
|
See also:
static IMPORT_C TAny *ReAllocL(TAny *aCell, TInt aSize, TInt aMode=0);
Description
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 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:
1. if the cell cannot be moved, i.e. aMode has the ENeverMove bit set, then the function leaves. 2. 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:
1. If reallocation fails, the content of the original cell is preserved.
2. 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.
Parameters
TAny *aCell |
A pointer to the cell to be reallocated. This may be NULL. |
TInt aSize |
The new size of the cell. This may be bigger or smaller than the size of the original cell. |
TInt aMode |
Flags controlling the reallocation. The only bit which has any effect on this function is that defined by the enumeration ENeverMove of the enum RAllocator::TReAllocMode. If this is set, then any successful reallocation guarantees not to have changed the start address of the cell. By default, this parameter is zero. |
|
Return value
TAny * |
A pointer to the reallocated cell. This may be the same as the original pointer supplied through aCell. |
|
Panic codes
USER |
42, if aCell is not NULL, and does not point to a valid cell. |
USER |
47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling ReAlloc(someptr,-1) raises this panic. |
|
See also:
static IMPORT_C RAllocator *SwitchAllocator(RAllocator *aAllocator);
Description
Changes the current thread's heap.
Parameters
RAllocator *aAllocator |
A pointer to the new heap handle. |
|
Return value
static inline RHeap *SwitchHeap(RAllocator *aHeap);
Description
Changes the current thread's heap.
Parameters
RAllocator *aHeap |
A pointer to the new heap handle. |
|
Return value
RHeap * |
A pointer to the old heap handle. |
|
static IMPORT_C TInt CompressAllHeaps();
Description
Compresses all the chunks containing heaps
Return value
TInt
|
KErrNone, if successful, otherwise one of the other system-wide codes. |
|
static IMPORT_C void After(TTimeIntervalMicroSeconds32 aInterval);
Description
Suspends the current thread until a specified time interval has expired.
Parameters
Panic codes
USER |
86, if the time interval is negative. |
|
static IMPORT_C TInt At(const TTime &aTime);
Description
Suspends the current thread until the specified absolute time.
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
const TTime &aTime |
The absolute time until which the current thread is to be suspended. |
|
Return value
TInt
|
On completion, contains the status of the request to suspend the current thread: |
|
static IMPORT_C void AfterHighRes(TTimeIntervalMicroSeconds32 aInterval);
Description
Suspends the current thread until a specified time interval has expired to a resolution of 1ms .
Parameters
Panic codes
USER |
86, if the time interval is negative. |
|
| Interface status: | deprecated | Set the time using User::SetUTCTime if the UTC time is known; otherwise, use the timezone server to set the time. |
| Capability: | WriteDeviceData | |
static IMPORT_C TInt SetHomeTime(const TTime &aTime);
Description
Sets the home time to a specified time value.
Parameters
const TTime &aTime |
A reference to a time representation object containing the time value. |
|
Return value
TInt
|
KErrNone if successful or one of the system-wide error codes. |
|
| Capability: | WriteDeviceData | |
static IMPORT_C TInt SetUTCTime(const TTime &aUTCTime);
Description
Sets the UTC time to a specified time value.
Parameters
Return value
TInt
|
KErrNone if successful or one of the system-wide error codes. |
|
static IMPORT_C TTimeIntervalSeconds UTCOffset();
Description
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
| Capability: | WriteDeviceData | |
static IMPORT_C void SetUTCOffset(TTimeIntervalSeconds aOffset);
Description
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
| Capability: | WriteDeviceData | |
static IMPORT_C TInt SetUTCTimeAndOffset(const TTime &aUTCTime, TTimeIntervalSeconds aOffset);
Description
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
Return value
TInt
|
KErrNone if successful or one of the system-wide error codes. |
|
| Capability: | WriteDeviceData | |
static IMPORT_C TInt SetCurrencySymbol(const TDesC &aSymbol);
Description
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
const TDesC &aSymbol |
A reference to the descriptor containing the currency symbol to be set. |
|
Return value
TInt
|
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. |
|
See also:
static IMPORT_C TUint TickCount();
Description
Gets the current tick count.
The period between ticks is usually 1/64 second, but may be hardware dependent.
Return value
TUint
|
The machine dependent tick count. |
|
static IMPORT_C TUint32 NTickCount();
Description
Gets the nanokernel tick count.
This is the current value of the machine's millisecond tick counter.
Return value
static IMPORT_C TTimerLockSpec LockPeriod();
Description
Returns which of the periods the clock is currently in.
Return value
static IMPORT_C TTimeIntervalSeconds InactivityTime();
Description
Gets the time since the last user activity.
Return value
static IMPORT_C void ResetInactivityTime();
Description
Resets all user inactivity timers.
static IMPORT_C TUint32 FastCounter();
Description
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.
Return value
static IMPORT_C TInt LockedInc(TInt &aValue);
Description
Increments a TInt value by 1 when the current thread is locked to prevent re-entrancy.
The increment to aValue is done while the current thread is locked; i.e. no other thread is permitted to run until the sequence of instructions which increment aValue have completed. Hence the function gives controlled access to a TInt variable which may be in a memory location accessible to more than one thread.
As an example of its use, the function is used in the implementation of critical sections.
Parameters
TInt &aValue |
A reference to an integer whose value is to be incremented. On return contains the incremented value. |
|
Return value
TInt
|
The value of aValue before it is incremented. |
|
See also:
User::LockedDecRCrticalSection
static IMPORT_C TInt LockedDec(TInt &aValue);
Description
Decrements a TInt value by 1 when the current thread is locked to prevent re-entrancy.
The decrement from aValue is done while the current thread is locked; i.e. no other thread is permitted to run until the sequence of instructions which decrement aValue have completed. Hence the function gives controlled access to a TInt variable which may be in a memory location accessible to more than one thread.
As an example of its use, the function is used in the implementation of critical sections.
Parameters
TInt &aValue |
A reference to TInt whose value is to be decremented. On return contains the decremented value. |
|
Return value
TInt
|
The value of aValue before it is decremented. |
|
See also:
User::LockedIncRCrticalSection
static IMPORT_C TInt SafeInc(TInt &aValue);
Description
Atomically increments the specified value by 1, if the value is > 0.
Parameters
TInt &aValue |
The value to be incremented; on return the incremented value. |
|
Return value
TInt
|
The original value of aValue |
|
static IMPORT_C TInt SafeDec(TInt &aValue);
Description
Atomically decrements the specified value by 1, if the value is > 0.
Parameters
TInt &aValue |
The value to be decremented; on return the decremented value. |
|
Return value
TInt
|
The original value of aValue |
|
static IMPORT_C TInt Beep(TInt aFrequency, TTimeIntervalMicroSeconds32 aDuration);
Description
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.
Parameters
Return value
static IMPORT_C TInt IsRomAddress(TBool &aBool, TAny *aPtr);
Description
Tests whether the specified address is in the ROM.
Parameters
TBool &aBool |
True, if the address at aPtr is within the ROM; false, otherwise. |
TAny *aPtr |
The address to be tested. |
|
Return value
static IMPORT_C TInt BinarySearch(TInt aCount, const TKey &aKey, TInt &aPos);
Description
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
TInt aCount |
The number of elements in the array. |
const TKey &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. |
TInt &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
TInt
|
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. |
|
static IMPORT_C TInt QuickSort(TInt aCount, const TKey &aKey, const TSwap &aSwap);
Description
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
TInt aCount |
The number of elements in the array. |
const TKey &aKey |
A reference to a suitably initialised TKey derived object. |
const TSwap &aSwap |
A reference to a suitably initialised TSwap derived object. |
|
Return value
TInt
|
KErrNone if the operation is successful; KErrGeneral otherwise. |
|
Panic codes
USER |
96, if aCount is negative. |
|
static IMPORT_C TLanguage Language();
Description
Gets the language of the current locale.
Return value
TLanguage
|
One of the TLanguage enumerators identifying the language of the current locale. |
|
static IMPORT_C TUint Collate(TUint aChar);
Description
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
TUint aChar |
The character to be folded. |
|
Return value
TUint
|
The converted character. |
|
| Interface status: | deprecated | |
static IMPORT_C TUint Fold(TUint aChar);
Description
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.
Parameters
TUint aChar |
The character to be folded. |
|
Return value
TUint
|
The folded character. |
|
See also:
![[Index]](../../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../../_stock/btn_next_wt.gif){kind=small}