diff -r c55016431358 -r 0a7b44b10206 symport/e32/include/e32base.inl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symport/e32/include/e32base.inl Thu Jun 25 15:59:54 2009 +0100 @@ -0,0 +1,3199 @@ +// Copyright (c) 1994-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Symbian Foundation License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// e32\include\e32base.inl +// +// + +// Class CBase +inline TAny* CBase::operator new(TUint aSize, TAny* aBase) __NO_THROW +/** +Initialises the object to binary zeroes. + +@param aSize The size of the derived class. This parameter is specified + implicitly by C++ in all circumstances in which a derived + class is allocated. +@param aBase Indicates a base address which is returned as the object's + address. + +@return A pointer to the base address. +*/ + { Mem::FillZ(aBase, aSize); return aBase; } + + + + +inline TAny* CBase::operator new(TUint aSize) __NO_THROW +/** +Allocates the object from the heap and then initialises its contents +to binary zeroes. + +@param aSize The size of the derived class. This parameter is specified + implicitly by C++ in all circumstances in which a derived class + is allocated. + +@return A pointer to the allocated object; NULL if memory could not + be allocated. +*/ + { return User::AllocZ(aSize); } + + + + +inline TAny* CBase::operator new(TUint aSize, TLeave) +/** +Allocates the object from the heap and then initialises its contents +to binary zeroes. + +@param aSize The size of the derived class. This parameter is specified + implicitly by C++ in all circumstances in which a derived class + is allocated. + +@return A pointer to the allocated object; the TLeave parameter indicates + that the operation leaves if allocation fails with out-of-memory. +*/ + { return User::AllocZL(aSize); } + + + + +inline TAny* CBase::operator new(TUint aSize, TUint aExtraSize) __NO_THROW +/** +Allocates the object from the heap and then initialises its contents +to binary zeroes. + +Use of this overload is rare. + +@param aSize The size of the derived class. This parameter is specified + implicitly by C++ in all circumstances in which a derived class + is allocated. + +@param aExtraSize Indicates additional size beyond the end of the base class. + +@return A pointer to the allocated object; NULL if memory could not + be allocated. +*/ + { return User::AllocZ(aSize + aExtraSize); } + + + + +inline TAny* CBase::operator new(TUint aSize, TLeave, TUint aExtraSize) +/** +Allocates the object from the heap and then initialises its contents +to binary zeroes. + +Use of this overload is rare. + +@param aSize The size of the derived class. This parameter is specified + implicitly by C++ in all circumstances in which a derived class + is allocated. + +@param aExtraSize Indicates additional size beyond the end of the base class. + +@return A pointer to the allocated object; the TLeave parameter indicates + that the operation leaves if allocation fails with out-of-memory. +*/ + { return User::AllocZL(aSize + aExtraSize); } + + + + +// Class CBufBase +inline TInt CBufBase::Size() const +/** +Gets the number of data bytes in the buffer. + +Note that the number of heap bytes used by the buffer may be greater than its +size, because there is typically extra room to allow for expansion. Use the +Compress() function to reduce the extra allocation as much as possible. + +@return The number of data bytes in the buffer. +*/ + {return(iSize);} + + + + +// Class CBufFlat +inline TInt CBufFlat::Capacity() const +/** +Gets the size to which the buffer may expand without re-allocation. + +@return The size of the allocated cell associated with the buffer. This is + the maximum size the buffer may be expanded to without re-allocation. +*/ + {return(iMaxSize);} + + + + +// Class CArrayFixBase +inline TInt CArrayFixBase::Count() const +/** +Gets the number of elements held in the array. + +@return The number of array elements +*/ + {return(iCount);} + + + + +inline TInt CArrayFixBase::Length() const +/** +Gets the length of an element. + +@return The length of an element of type class T. +*/ + {return(iLength);} + + + + +// Template class CArrayFix +template +inline CArrayFix::CArrayFix(TBufRep aRep,TInt aGranularity) + : CArrayFixBase(aRep,sizeof(T),aGranularity) +/** +@internalComponent +*/ + {} + + + + +template +inline const T &CArrayFix::operator[](TInt anIndex) const +/** +Gets a const reference to the element located at the specified position +within the array. + +Note that if a pointer to the returned referenced class T object is taken, +be aware that the pointer value becomes invalid once elements have been added +to, or removed from the array. Always refresh the pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A const reference to the required element. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((const T *)CArrayFixBase::At(anIndex)));} + + + + +template +inline T &CArrayFix::operator[](TInt anIndex) +/** +Gets a non-const reference to the element located at the specified position +within the array. + +Note that if a pointer to the returned referenced class T object is taken, +be aware that the pointer value becomes invalid once elements have been added +to, or removed from the array. Always refresh the pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A non-const reference to the required element. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((T *)CArrayFixBase::At(anIndex)));} + + + + +template +inline const T &CArrayFix::At(TInt anIndex) const +/** +Gets a const reference to the element located at the specified position +within the array. + +Note that if a pointer to the returned referenced class T object is taken, +be aware that the pointer value becomes invalid once elements have been added +to, or removed from the array. Always refresh the pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A const reference to the required element. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((const T *)CArrayFixBase::At(anIndex)));} + + + + +template +inline const T *CArrayFix::End(TInt anIndex) const +/** +Gets a pointer to the (const) first byte following the end of the +contiguous region containing the element at the specified position within +the array. + +For arrays implemented using flat buffers, the pointer always points to the +first byte following the end of the buffer. + +For arrays implemented using segmented buffers, the pointer always points +to the first byte following the end of the segment which contains the element. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element + in the array. + +@return A pointer to the constant byte following the end of the contiguous + region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return((const T *)CArrayFixBase::End(anIndex));} + + + + +template +inline const T *CArrayFix::Back(TInt anIndex) const +/** +Gets a pointer to the (const) beginning of a contiguous region. + +For arrays implemented using flat buffers, the function always returns a +pointer to the beginning of the buffer. + +For arrays implemented using segmented buffers, the function returns a pointer +to the beginning of the segment for all elements in that segment except the +first. If the element at position anIndex is the first in a segment, then +the function returns a pointer the beginning of the previous segment. + +For the first element in the array, the function returns a NULL pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element + in the array. + +@return A pointer to the (const) beginning of the contiguous region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return((const T *)CArrayFixBase::Back(anIndex));} + + + + +template +inline T &CArrayFix::At(TInt anIndex) +/** +Gets a non-const reference to the element located at the specified position +within the array. + +Note that if a pointer to the returned referenced class T object is taken, +be aware that the pointer value becomes invalid once elements have been added +to, or removed from the array. Always refresh the pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A non-const reference to the required element. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((T *)CArrayFixBase::At(anIndex)));} + + + + +template +inline T *CArrayFix::End(TInt anIndex) +/** +Gets a pointer to the first byte following the end of the contiguous region +containing the element at the specified position within the array. + +For arrays implemented using flat buffers, the pointer always points to the +first byte following the end of the buffer. + +For arrays implemented using segmented buffers, the pointer always points +to the first byte following the end of the segment which contains the element. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element + in the array. + +@return A pointer to the byte following the end of the contiguous region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(((T *)CArrayFixBase::End(anIndex)));} + + + + +template +inline T *CArrayFix::Back(TInt anIndex) +/** +Gets a pointer to the beginning of a contiguous region. + +For arrays implemented using flat buffers, the function always returns a pointer +to the beginning of the buffer. + +For arrays implemented using segmented buffers, the function returns a pointer +to the beginning of the segment for all elements in that segment except the +first. If the element at position anIndex is the first in a segment, then +the function returns a pointer the beginning of the previous segment. + +For the first element in the array, the function returns a NULL pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element + in the array. + +@return A pointer to the beginning of the contiguous region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(((T *)CArrayFixBase::Back(anIndex)));} + + + + +template +inline void CArrayFix::AppendL(const T &aRef) +/** +Appends a single element onto the end of the array. + +@param aRef A reference to the class T element to be appended. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +*/ + {CArrayFixBase::InsertL(Count(),&aRef);} + + + + +template +inline void CArrayFix::AppendL(const T *aPtr,TInt aCount) +/** +Appends one or more elements onto the end of the array. + +@param aPtr A pointer to a contiguous set of type objects to be + appended. +@param aCount The number of contiguous objects of type located at + aPtr to be appended. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@panic E32USER-CBase 23, if aCount is negative. +*/ + {CArrayFixBase::InsertL(Count(),aPtr,aCount);} + + + + +template +inline void CArrayFix::AppendL(const T &aRef,TInt aReplicas) +/** +Appends replicated copies of an element onto the end of the array. + +@param aRef A reference to the object to be replicated and appended. +@param aReplicas The number of copies of the aRef element to be appended. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@panic E32USER-CBase 28 if aReplicas is negative. +*/ + {CArrayFixBase::InsertRepL(Count(),&aRef,aReplicas);} + + + + +template +inline T &CArrayFix::ExpandL(TInt anIndex) +/** +Expands the array by one element at the specified position. + +It: + +1. expands the array by one element at the specified position + +2. constructs a new element at that position + +3. returns a reference to the new element. + +All existing elements from position anIndex to the end of the array are moved +up, so that the element originally at position anIndex is now at position +anIndex + 1 etc. + +The new element of type class T is constructed at position anIndex, using +the default constructor of that class. + +@param anIndex The position within the array where the array is to be expanded + and the new class T object is to be constructed. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@return A reference to the newly constructed class T object at position + anIndex within the array. + +@panic E32USER-CBase 21 if anIndex is negative or greater than the number + of elements currently in the array. +*/ + {return(*new(CArrayFixBase::ExpandL(anIndex)) T);} + + + + +template +inline T &CArrayFix::ExtendL() +/** +Expands the array by one element at the end of the array. + +It: + +1. expands the array by one element at the end of the array, i.e. at position + CArrayFixBase::Count() + +2. constructs a new element at that position + +3. returns a reference to the new element. + +The new element of type class T is constructed at the end of the array, +using the default constructor of that class. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@return A reference to the newly constructed class T object at the end of + the array. + +@see CArrayFixBase::Count +*/ + {return(*new(CArrayFixBase::ExpandL(Count())) T);} + + + + +template +inline TInt CArrayFix::Find(const T &aRef,TKeyArrayFix &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a sequential search. + +The array is searched sequentially for an element whose key matches the key of the +supplied class T object. The search starts with the first element in the array. + +Note that where an array has elements with duplicate keys, the function only +supplies the position of the first element in the array with that key. + +@param aRef A reference to an object of type class T whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A reference to a TInt supplied by the caller. On return, 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 value of the reference is set to the number of elements in + the array. + If the element is not found and the array is empty, then the + reference is set to zero. + +@return Zero, if the element with the specified key is found. + Non-zero, if the element with the specified key is not found. +*/ + {return(CArrayFixBase::Find(&aRef,aKey,anIndex));} + + + + +template +inline TInt CArrayFix::FindIsq(const T &aRef,TKeyArrayFix &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a binary search technique. + +The array is searched, using a binary search technique, for an element whose +key matches the key of the supplied class T object. + +The array must be in key order. + +Note that where an array has elements with duplicate keys, the function cannot +guarantee which element, with the given key value, it will return, except that +it will find one of them. + +@param aRef A reference to an object of type class T whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A reference to a TInt supplied by the caller. On return, 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 key of the + object aRef. + If the element is not found and the array is empty, then the + reference is set to zero. + +@return Zero, if the element with the specified key is found. + Non-zero, if the element with the specified key is not found. +*/ + {return(CArrayFixBase::FindIsq(&aRef,aKey,anIndex));} + + + + +template +inline void CArrayFix::InsertL(TInt anIndex,const T &aRef) +/** +Inserts an element into the array at the specified position. + +Note that passing a value of anIndex which is the same as the current number +of elements in the array, has the effect of appending the element. + +@param anIndex The position within the array where the element is to be + inserted. The position is relative to zero, i.e. zero implies + that elements are inserted at the beginning of the array. + +@param aRef A reference to the class T object to be inserted into the array + at position anIndex. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@panic E32USER-CBase 21 if anIndex is negative, or is greater than the number + of elements currently in the array. +*/ + {CArrayFixBase::InsertL(anIndex,&aRef);} + + + + +template +inline void CArrayFix::InsertL(TInt anIndex,const T *aPtr,TInt aCount) +/** +Inserts one or more elements into the array at the specified position. + +The objects to be added must all be contiguous. + +Note that passing a value of anIndex which is the same as the current number +of elements in the array, has the effect of appending the element. + +@param anIndex The position within the array where the elements are to be + inserted. The position is relative to zero, i.e. zero implies + that elements are inserted at the beginning of the array. + +@param aPtr A pointer to the first of the contiguous elements of type + class T to be inserted into the array at position anIndex. + +@param aCount The number of contiguous elements of type class T located at + aPtr to be inserted into the array. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@panic E32USER-CBase 21 if anIndex is negative or is greater than the number + of elements currently in the array. +@panic E32USER-CBase 23 if aCount is negative. +*/ + {CArrayFixBase::InsertL(anIndex,aPtr,aCount);} + + + + +template +inline void CArrayFix::InsertL(TInt anIndex,const T &aRef,TInt aReplicas) +/** +Inserts replicated copies of an element into the array at the specified +position. + +Note that passing a value of anIndex which is the same as the current number +of elements in the array, has the effect of appending the element. + + +@param anIndex The position within the array where elements are to be + inserted. The position is relative to zero, i.e. zero implies + that elements are inserted at the beginning of the array. + +@param aRef A reference to the class T object to be replicated and + inserted into the array at position anIndex. + +@param aReplicas The number of copies of the aRef element to be inserted into + the array. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. + +@panic E32USER-CBase 21, if anIndex is negative or is greater than the number + of elements currently in the array. +@panic E32USER-CBase 28, if aReplicas is negative. +*/ + {CArrayFixBase::InsertRepL(anIndex,&aRef,aReplicas);} + + + + +template +inline TInt CArrayFix::InsertIsqL(const T &aRef,TKeyArrayFix &aKey) +/** +Inserts a single element into the array at a position determined by a key. + +The array MUST already be in key sequence (as defined by the key), otherwise +the position of the new element is unpredictable, or duplicates may occur. + +Elements with duplicate keys are not permitted. + +@param aRef A reference to the element of type to be inserted into + the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrAlreadyExists An element with the same key already exists within + the array. NB the array MUST already be in key sequence, otherwise + the function may insert a duplicate and fail to leave with + this value. +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +*/ + {return(CArrayFixBase::InsertIsqL(&aRef,aKey));} + + + + +template +inline TInt CArrayFix::InsertIsqAllowDuplicatesL(const T &aRef,TKeyArrayFix &aKey) +/** +Inserts a single element into the array at a position determined by a key, +allowing duplicates. + +The array MUST already be in key sequence (as defined by the key), otherwise +the position of the new element is unpredictable. + +If the new element's key is a duplicate of an existing element's key, then +the new element is positioned after the existing element. + +@param aRef A reference to the element of type to be inserted into + the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +*/ + {return(CArrayFixBase::InsertIsqAllowDuplicatesL(&aRef,aKey));} + + + + +template +inline void CArrayFix::ResizeL(TInt aCount) +/** +Changes the size of the array so that it contains the specified number +of elements. + +The following describes the effects of calling this function: + +1. If aCount is less than the current number of elements in the array, then the + array is shrunk. The elements at positions aCount and above are discarded. + The array buffer is not compressed. + +2. If aCount is greater than the current number of elements in the array, then + the array is extended. + +3. New elements are replicated copies of an object of type , + constructed using the default constructor of that class. + +The new elements are positioned after the existing elements in the array. + +The function may attempt to expand the array buffer. If there is insufficient +memory available, the function leaves. The leave code is one of the system +wide error codes. If the function leaves, the array is left in the state it +was in before the call. + +@param aCount The number of elements the array is to contain after the resizing + operation. + +@panic E32USER-CBase 24, if aCount is negative. +*/ + {TUint8 b[sizeof(T)]; new(&b[0]) T; CArrayFixBase::ResizeL(aCount,&b[0]);} + + + + +template +inline void CArrayFix::ResizeL(TInt aCount,const T &aRef) +/** +Changes the size of the array so that it contains the specified number +of elements. + +The following describes the effects of calling this function: + +1. If aCount is less than the current number of elements in the array, then the + array is shrunk. The elements at positions aCount and above are discarded. + The array buffer is not compressed. + +2. If aCount is greater than the current number of elements in the array, then + the array is extended. + +3. New elements are replicated copies of aRef. + +The new elements are positioned after the existing elements in the array. + +The function may attempt to expand the array buffer. If there is insufficient +memory available, the function leaves. The leave code is one of the system +wide error codes. If the function leaves, the array is left in the state it +was in before the call. + +@param aCount The number of elements the array is to contain after the resizing + operation. + +@param aRef A reference to an object of type , copies of which are + used as the new elements of the array, if the array is extended. + +@panic E32USER-CBase 24, if aCount is negative. +*/ + {CArrayFixBase::ResizeL(aCount,&aRef);} + + + + +template +inline const TArray CArrayFix::Array() const +/** +Constructs and returns a TArray object. + +@return A TArray object representing this array. +*/ + {return(TArray(CountR,AtR,this));} + + + + +inline CArrayFix::CArrayFix(TBufRep aRep,TInt aRecordLength,TInt aGranularity) + : CArrayFixBase(aRep,aRecordLength,aGranularity) +/** +@internalComponent +*/ + {} + + + + +inline const TAny *CArrayFix::At(TInt anIndex) const +/** +Gets a pointer to the untyped element located at the specified position +within the array. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in the + array. + +@return A pointer to the untyped element located at position anIndex within + the array. + +@panic E32User-CBase 21, if anIndex is negative or is greater than or equal + to the number of objects currently within the array. +*/ + {return(CArrayFixBase::At(anIndex));} + + + + +inline const TAny *CArrayFix::End(TInt anIndex) const +/** +Gets a pointer to the first byte following the end of the contiguous region +containing the element at the specfied position within the array. + +For flat buffers, the pointer always points to the first byte following the +end of the buffer. + +For segmented buffers, the pointer always points to the first byte following +the end of the segment which contains the element. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A pointer to the byte following the end of the contiguous region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayFixBase::End(anIndex));} + + + + +inline const TAny *CArrayFix::Back(TInt anIndex) const +/** +Gets a pointer to the beginning of a contiguous region. + +For flat buffers, the function always returns a pointer to the beginning of +the buffer. + +For segmented buffers, the function returns a pointer to the beginning of +the segment for all elements in that segment except the first. If the element +at the specified position is the first in a segment, then the function returns +a pointer the beginning of the previous segment. + +For the first element in the array, the function returns a NULL pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in the array. + +@return A pointer to the beginning of the contiguous region. + +@panic E32User-CBase 21, if anIndex is negative or is greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayFixBase::Back(anIndex));} + + + + +inline TAny *CArrayFix::At(TInt anIndex) +/** +Gets a pointer to the untyped element located at the specified position +within the array. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in the + array. + +@return A pointer to the untyped element located at position anIndex within + the array. + +@panic E32User-CBase 21, if anIndex is negative or is greater than or equal + to the number of objects currently within the array. +*/ + {return(CArrayFixBase::At(anIndex));} + + + + +inline TAny *CArrayFix::End(TInt anIndex) +/** +Gets a pointer to the first byte following the end of the contiguous region +containing the element at the specfied position within the array. + +For flat buffers, the pointer always points to the first byte following the +end of the buffer. + +For segmented buffers, the pointer always points to the first byte following +the end of the segment which contains the element. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A pointer to the byte following the end of the contiguous region. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayFixBase::End(anIndex));} + + + + +inline TAny *CArrayFix::Back(TInt anIndex) +/** +Gets a pointer to the beginning of a contiguous region. + +For flat buffers, the function always returns a pointer to the beginning of +the buffer. + +For segmented buffers, the function returns a pointer to the beginning of +the segment for all elements in that segment except the first. If the element +at the specified position is the first in a segment, then the function returns +a pointer the beginning of the previous segment. + +For the first element in the array, the function returns a NULL pointer. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in the array. + +@return A pointer to the beginning of the contiguous region. + +@panic E32User-CBase 21, if anIndex is negative or is greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayFixBase::Back(anIndex));} + + + + +inline void CArrayFix::AppendL(const TAny *aPtr) +/** +Appends the specified untyped element onto the end of the array. + +@param aPtr A pointer to an untyped element to be appended. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +*/ + {CArrayFixBase::InsertL(Count(),aPtr);} + + + + +inline void CArrayFix::AppendL(const TAny *aPtr,TInt aCount) +/** +Appends one or more untyped elements onto the end of the array. + +@param aPtr A pointer to the first of the contiguous untyped elements to be + appended. +@param aCount The number of contiguous elements located at aPtr to be appended. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +@panic E32USER-CBase 23, if aCount is negative. +*/ + {CArrayFixBase::InsertL(Count(),aPtr,aCount);} + + + + +inline TAny *CArrayFix::ExtendL() +/** +Expands the array by the length of one element at the end of the array and +returns a pointer to this new location. + +As elements are untyped, no construction is possible and the content of the +new location remains undefined. + +@return A pointer to the new element location at the end of the array. + +@leave KErrNoMemory The function may attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case the array is left in the state it was in before the call. +*/ + {return(CArrayFixBase::ExpandL(Count()));} + + + + +// Template class CArrayFixFlat +template +inline CArrayFixFlat::CArrayFixFlat(TInt aGranularity) + : CArrayFix((TBufRep)CBufFlat::NewL,aGranularity) +/** +Constructs a flat array of fixed length objects with the specified granularity. + +The length of all array elements is the length of the class passed as the +template parameter. The length must be non-zero. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 17, if the length of the class implied by the template parameter is zero. + +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +template +inline void CArrayFixFlat::SetReserveL(TInt aCount) +/** +Reserves space in the array buffer. + +If necessary, the array buffer is allocated or re-allocated so that it can +accommodate the specified number of elements. + +After a successful call to this function, elements can be added to the array +and the process is guaranteed not to fail for lack of memory - provided the +total number of elements does not exceed the number specified in this function. + +This function does not increase the number of elements in the array; i.e. +the member function CArrayFixBase::Count() returns the same value both before +and after a call to CArrayFixFlat::SetReserveL(). + +@param aCount The total number of elements for which space is to be reserved. + +@panic E32USER-CBase 27, if aCount is less than the current number of elements + in the array. +*/ + {this->SetReserveFlatL(aCount);} + + + + +inline CArrayFixFlat::CArrayFixFlat(TInt aRecordLength,TInt aGranularity) + : CArrayFix((TBufRep)CBufFlat::NewL,aRecordLength,aGranularity) +/** +Constructs a flat array of fixed length objects with the specified granularity +to contain elements of the specified length. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aRecordLength The length of the elements of this fixed length array. +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 17, if aRecordLength is not positive. +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +inline void CArrayFixFlat::SetReserveL(TInt aCount) +/** +Reserves space in the array buffer. + +If necessary, the array buffer is allocated or re-allocated so that it can +accommodate the specified number of elements. + +After a successful call to this function, elements can be added to the array +and the process is guaranteed not to fail for lack of memory - provided the +total number of elements does not exceed the specified number. + +This function does not increase the number of elements in the array; i.e. +the member function CArrayFixBase::Count() returns the same value both before +and after a call to this function. + +@param aCount The total number of elements for which space is to be reserved. + +@panic E32USER-CBase 27, if aCount is less than the current number of elements + in the array. +*/ + {SetReserveFlatL(aCount);} + + + + +inline void CArrayFixFlat::SetReserveL(TInt aCount) +/** +Reserves space in the array buffer. + +If necessary, the array buffer is allocated or re-allocated so that it can +accommodate the specified number of TInt elements. + +After a successful call to this function, elements can be added to the array +and the process is guaranteed not to fail for lack of memory - provided the +total number of elements does not exceed the specified number. + +This function does not increase the number of elements in the array; i.e. +the member function CArrayFixBase::Count() returns the same value both before +and after a call to this function. + +@param aCount The total number of elements for which space is to be reserved. + +@panic E32USER-CBase 27, if aCount is less than the current number of elements + in the array. +*/ + {SetReserveFlatL(aCount);} + + + + +inline void CArrayFixFlat::SetReserveL(TInt aCount) +/** +Reserves space in the array buffer. + +If necessary, the array buffer is allocated or re-allocated so that it can +accommodate the specified number of TUid elements. + +After a successful call to this function, elements can be added to the array +and the process is guaranteed not to fail for lack of memory - provided the +total number of elements does not exceed the specified number. + +This function does not increase the number of elements in the array; i.e. +the member function CArrayFixBase::Count() returns the same value both before +and after a call to this function. + +@param aCount The total number of elements for which space is to be reserved. + +@panic E32USER-CBase 27, if aCount is less than the current number of elements + in the array. +*/ + {SetReserveFlatL(aCount);} + + + + +// Template class CArrayFixSeg +template +inline CArrayFixSeg::CArrayFixSeg(TInt aGranularity) + : CArrayFix((TBufRep)CBufSeg::NewL,aGranularity) +/** +Constructs a segmented array of fixed length objects with the specified +granularity. + +The length of all array elements is the length of the class passed as the +template parameter. The length must be non-zero. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 17, if the length of the class implied by the template + parameter is zero. +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +inline CArrayFixSeg::CArrayFixSeg(TInt aRecordLength,TInt aGranularity) + : CArrayFix((TBufRep)CBufSeg::NewL,aRecordLength,aGranularity) +/** +Constructs a segmented array of fixed length objects with the specified +granularity to contain elements of the specified length. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aRecordLength The length of the elements of this array. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 17, if aRecordLength is not positive. +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +// Template class CArrayPtr +template +inline CArrayPtr::CArrayPtr(TBufRep aRep,TInt aGranularity) + : CArrayFix(aRep,aGranularity) +/** +@internalComponent +*/ + {} + + + + +template +void CArrayPtr::ResetAndDestroy() +/** +Destroys all objects whose pointers form the elements of the array, before +resetting the array. + +The destructor of each class T object is called before the objects themselves +are destroyed. + +If the array is not empty, this member function must be called before the +array is deleted to prevent the CBase derived objects from being orphaned +on the heap. + +Note that each call to this function results in a small, but non-trivial, +amount of code being generated. +*/ + { + for (TInt i=0;iCount();++i) + delete this->At(i); + this->Reset(); + } + + + + +// Template class CArrayPtrFlat +template +inline CArrayPtrFlat::CArrayPtrFlat(TInt aGranularity) + : CArrayPtr((TBufRep)CBufFlat::NewL,aGranularity) +/** +Constructs a flat array of pointers with specified granularity. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +template +inline void CArrayPtrFlat::SetReserveL(TInt aCount) +/** +Reserves space in the array buffer. + +If necessary, the array buffer is allocated or re-allocated so that it can +accommodate the specified number of elements. + +After a successful call to this function, elements can be added to the array +and the process is guaranteed not to fail for lack of memory - provided the +total number of elements does not exceed the specified number. + +This function does not increase the number of elements in the array; i.e. +the member function CArrayFixBase::Count() returns the same value both before +and after a call to this function. + +@param aCount The total number of elements for which space is to be reserved. + +@panic E32USER-CBase 27, if aCount is less than the current number of elements + in the array. +*/ + {this->SetReserveFlatL(aCount);} + + + + +// Template class CArrayPtrSeg +template +inline CArrayPtrSeg::CArrayPtrSeg(TInt aGranularity) + : CArrayPtr((TBufRep)CBufSeg::NewL,aGranularity) +/** +Constructs a segmented array of pointers with specified granularity. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 18, if aGranularity is not positive. +*/ + {} + + + + +// Class CArrayVarBase +inline TInt CArrayVarBase::Count() const +/** +Gets the number of elements held in the array. + +@return The number of array elements. +*/ + {return(iCount);} + + + + +// Template class CArrayVar +template +inline CArrayVar::CArrayVar(TBufRep aRep,TInt aGranularity) + : CArrayVarBase(aRep,aGranularity) +/** +@internalComponent +*/ + {} + + + + +template +inline const T &CArrayVar::operator[](TInt anIndex) const +/** +Gets a reference to the const element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where it cannot be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((const T *)CArrayVarBase::At(anIndex)));} + + + + +template +inline T &CArrayVar::operator[](TInt anIndex) +/** +Gets a reference to the element located at the specified position within +the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where it can be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + + +@return A reference to the non-const element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((T *)CArrayVarBase::At(anIndex)));} + + + + +template +inline const T &CArrayVar::At(TInt anIndex) const +/** +Gets a reference to the const element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where it cannot be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((const T *)CArrayVarBase::At(anIndex)));} + + + +template +inline T &CArrayVar::At(TInt anIndex) +/** +Gets a reference to the element located at the specified position within +the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where it can be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A reference to the non-const element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(*((T *)CArrayVarBase::At(anIndex)));} + + + + +template +inline void CArrayVar::AppendL(const T &aRef,TInt aLength) +/** +Appends an element of a specified length onto the array. + +@param aRef A reference to the element to be appended. +@param aLength The length of the element to be appended. + +@leave KErrNoMemory The function always attempts to allocate a cell to + contain the new element and may also attempt to expand the array buffer. + If there is insufficient memory available, the function leaves, in which + case, the array is left in the state it was in before the call. + +@panic E32USER-CBase 30, if aLength is negative. +*/ + {CArrayVarBase::InsertL(Count(),&aRef,aLength);} + + + + +template +inline T &CArrayVar::ExpandL(TInt anIndex,TInt aLength) +/** +Expands the array by one element of specified length at the specified position. + +It: + +1. expands the array by one element position anIndex + +2. constructs a new element of specified length at that position + +3. returns a reference to the new element. + +All existing elements from position anIndex to the end of the array are moved +up, so that the element originally at position anIndex is now at position +anIndex + 1 etc. + +The new element of type and length aLength is constructed at position +anIndex, using the default constructor of that class. + +@param anIndex The position within the array where the array is to be expanded + and the new object is to be constructed. + +@param aLength The length of the new element. + +@return A reference to the newly constructed object at position + anIndex within the array. + +@leave KErrNoMemory The function always attempts to allocate a cell to contain + the new element and may also attempt to expand the array buffer. If there + is insufficient memory available, the function leaves, in which case, the + array is left in the state it was in before the call. + +@panic E32USER-CBase 21, if anIndex is negative or is greater than the number + of elements currently in the array. +@panic E32USER-CBase 30, if aLength is negative. +*/ + {return(*new(CArrayVarBase::ExpandL(anIndex,aLength)) T);} + + + + +template +inline T &CArrayVar::ExtendL(TInt aLength) +/** +Expands the array by one element of specified length at the end of the array. + +It: + +1. expands the array by one element at the end of the array, i.e. at position + CArrayVarBase::Count() + +2. constructs a new element of specified length at that position. + +3. returns a reference to the new element. + +The new element of type is constructed at the end of the array, +using the default constructor of that class. + +@param aLength The length of the new element. + +@return A reference to the newly constructed object at the end of + the array. + +@leave KErrNoMemory The function always attempts to allocate a cell to contain + the new element and may also attempt to expand the array buffer. If there + is insufficient memory available, the function leaves, in which case, the + array is left in the state it was in before the call. + +@panic E32USER-CBase 30, if aLength is negative. +*/ + {return(*new(CArrayVarBase::ExpandL(Count(),aLength)) T);} + + + + +template +inline TInt CArrayVar::Find(const T &aRef,TKeyArrayVar &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a sequential search. + +The array is searched sequentially for an element whose key matches the key +of the supplied object. The search starts with the first element in the array. + +Note that where an array has elements with duplicate keys, the function only +supplies the position of the first element in the array with that key. + +@param aRef A reference to an object of type whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A TInt supplied by the caller. On return, if the element is + found, this 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 or the array is empty, then + this is undefined. + +@return Zero, if the element with the specified key is found. Non-zero, if + the element with the specified key is not found. +*/ + {return(CArrayVarBase::Find(&aRef,aKey,anIndex));} + + + + +template +inline TInt CArrayVar::FindIsq(const T &aRef,TKeyArrayVar &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a binary search technique. + +The array is searched, using a binary search technique, for an element whose +key matches the key of the supplied object. + +The array must be in key order. + +Note that where an array has elements with duplicate keys, the function cannot +guarantee which element, with the given key value, it will return, except that +it will find one of them. + +@param aRef A reference to an object of type whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A TInt supplied by the caller. On return, if the element is + found, this 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 zero). + If the element is not found and the array is not empty, then + this is set to the position of the first element in the array + with a key which is greater than the key of the object aRef. + If the element is not found and the array is empty, then + this is undefined. + +@return Zero, if the element with the specified key is found or the array is + empty. Non-zero, if the element with the specified key is not found. +*/ + {return(CArrayVarBase::FindIsq(&aRef,aKey,anIndex));} + + + + +template +inline void CArrayVar::InsertL(TInt anIndex,const T &aRef,TInt aLength) +/** +Inserts an element of a specified length into the array at the specified +position. + +Note that passing a value of anIndex which is the same as the current number +of elements in the array, has the effect of appending that element. + +@param anIndex The position within the array where the element is to be + inserted. The position is relative to zero, i.e. zero implies + that elements are inserted at the beginning of the array. +@param aRef A reference to the object to be inserted into + the array. +@param aLength The length of the element to be inserted into the array. + +@leave KErrNoMemory The function always attempts to allocate a cell to contain + the new element and may also attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case, the array is left in the state it was in before the call. + +@panic E32USER-CBase 21, if anIndex is negative or is greater than the number + of objects currently in the array. +@panic E32USER-CBase 30, if aLength is is negative. +*/ + {CArrayVarBase::InsertL(anIndex,&aRef,aLength);} + + + + +template +inline TInt CArrayVar::InsertIsqL(const T &aRef,TInt aLength,TKeyArrayVar &aKey) +/** +Inserts a single element of a specified length into the array at a position +determined by a key. + +The array MUST already be in key sequence (as defined by the key), otherwise +the position of the new element is unpredictable, or duplicates may occur. + +Elements with duplicate keys are not permitted. + +@param aRef A reference to the element of type to be inserted into + the array. +@param aLength The length of the new element of type to be inserted + into the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrAlreadyExists An element with the same key already exists within + the array. NB the array MUST already be in key sequence, otherwise + the function may insert a duplicate and fail to leave with + this value. +@leave KErrNoMemory The function always attempts to allocate a cell to contain + the new element and may also attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case, the array is left in the state it was in before the call. +*/ + {return(CArrayVarBase::InsertIsqL(&aRef,aLength,aKey));} + + + + +template +inline TInt CArrayVar::InsertIsqAllowDuplicatesL(const T &aRef,TInt aLength,TKeyArrayVar &aKey) +/** +Inserts a single element of a specified length into the array at a position +determined by a key, allowing duplicates. + +The array MUST already be in key sequence, otherwise the position of the +new element is unpredictable. + +Elements with duplicate keys are permitted. If the new element's key is a +duplicate of an existing element's key, then the new element is positioned +after the existing element. + +@param aRef A reference to the element of type to be inserted + into the array. +@param aLength The length of the new element to be inserted into the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrNoMemory The function always attempts to allocate a cell to contain + the new element and may also attempt to expand the array buffer. If + there is insufficient memory available, the function leaves, in which + case, the array is left in the state it was in before the call. +*/ + {return(CArrayVarBase::InsertIsqAllowDuplicatesL(&aRef,aLength,aKey));} + + + + +template +inline const TArray CArrayVar::Array() const +/** +Constructs and returns a TArray object. + +@return A TArray object for this array. +*/ + {return(TArray(CountR,AtR,this));} + + + + +inline const TAny *CArrayVar::At(TInt anIndex) const +/** +Returns a pointer to the untyped element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned pointer is +used in an expression where it cannot be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A pointer to the const element located at position anIndex within the + array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(CArrayVarBase::At(anIndex));} + + + + +inline CArrayVar::CArrayVar(TBufRep aRep,TInt aGranularity) + : CArrayVarBase(aRep,aGranularity) +/** +Constructs a variable array with the specified granularity and buffer +organization. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aRep A pointer to a function used to expand the array buffer. + The organisation of the array buffer is implied by the + choice of this function. + For a flat array buffer, pass (TBufRep)CBufFlat::NewL. + For a segmented array buffer, pass (TBufRep)CBufSeg::NewL. +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 19, if aGranularity is not positive. +*/ + {} + + + + +inline TAny *CArrayVar::At(TInt anIndex) +/** +Returns a pointer to the untyped element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned pointer is +used in an expression where it can be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A pointer to the non-const element located at position anIndex within the + array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to the + number of objects currently within the array. +*/ + {return(CArrayVarBase::At(anIndex));} + + + + +inline void CArrayVar::AppendL(const TAny *aPtr,TInt aLength) +/** +Appends an untyped element of specified length onto the end of the array. + +@param aPtr A pointer to an untyped element to be appended. +@param aLength The length of the untyped element. +*/ + {CArrayVarBase::InsertL(Count(),aPtr,aLength);} + + + + +inline TAny *CArrayVar::ExtendL(TInt aLength) +/** +Extends the array by one element of specified length at the end of the array, +i.e. at position CArrayVarBase::Count(), and returns a pointer to the new +element location. + +As elements are untyped, no construction is possible and the content of the +new location remains undefined. + +Note that the function always attempts to allocate a cell to contain the new +element and may also attempt to expand the array buffer. If there is +insufficient memory available, the function leaves. +The leave code is one of the system wide error codes. +If the function leaves, the array is left in the state it was in before +the call. + +@param aLength The length of the new element. + +@return A pointer to the new element location at the end of the array. +*/ + {return(CArrayVarBase::ExpandL(Count(),aLength));} + + + + +// Template class CArrayVarFlat +template +inline CArrayVarFlat::CArrayVarFlat(TInt aGranularity) + : CArrayVar((TBufRep)CBufFlat::NewL,aGranularity) +/** +Constructs a variable flat array with specified granularity. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 19, if aGranularity is not positive. +*/ + {} + + + + +// Template class CArrayVarSeg +template +inline CArrayVarSeg::CArrayVarSeg(TInt aGranularity) + : CArrayVar((TBufRep)CBufSeg::NewL,aGranularity) +/** +Constructs a variable segmented array with specified granularity. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 19, if aGranularity is not positive. +*/ + {} + + + + +// Class CArrayPakBase +inline TInt CArrayPakBase::Count() const +/** +Gets the number of elements held in the array. + +@return The number of array elements. +*/ + {return(iCount);} + + + + +// Template class CArrayPak +template +inline CArrayPak::CArrayPak(TBufRep aRep,TInt aGranularity) + : CArrayPakBase(aRep,aGranularity) +/** +@internalComponent +*/ + {} + + + + +template +inline const T &CArrayPak::operator[](TInt anIndex) const +/** +Gets a reference to the element located at the specified position within the +array. + +The compiler uses this variant of the function when the returned reference +is used in an expression where it cannot be modified. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + number of objects currently within the array. +*/ + {return(*((const T *)CArrayPakBase::At(anIndex)));} + + + + +template +inline T &CArrayPak::operator[](TInt anIndex) +/** +Gets a reference to the element located at the specified position within the +array. + +The compiler uses this variant of the function when the returned reference +is used in an expression where it can be modified. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A non-const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + number of objects currently within the array. +*/ + {return(*((T *)CArrayPakBase::At(anIndex)));} + + + + +template +inline const T &CArrayPak::At(TInt anIndex) const +/** +Gets a reference to the element located at the specified position within the +array. + +The compiler uses this variant of the function when the returned reference +is used in an expression where it cannot be modified. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + number of objects currently within the array. +*/ + {return(*((const T *)CArrayPakBase::At(anIndex)));} + + + + +template +inline T &CArrayPak::At(TInt anIndex) +/** +Gets a reference to the element located at the specified position within the +array. + +The compiler uses this variant of the function when the returned reference +is used in an expression where it can be modified. + +@param anIndex The position of the element within the array. The position + is relative to zero; i.e. zero implies the first element in + the array. + +@return A non-const reference to the element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + number of objects currently within the array. +*/ + {return(*((T *)CArrayPakBase::At(anIndex)));} + + + + +template +inline void CArrayPak::AppendL(const T &aRef,TInt aLength) +/** +Appends an element of a specified length onto the array. + +@param aRef A reference to the class T element to be appended. +@param aLength The length of the element to be appended. + +@leave KErrNoMemory The function attempted to allocate from the heap and there + is insufficient memory available. In this case, the array is left in + the state it was in before the call. + +@panic E32USER-CBase 30, if aLength is negative. +*/ + {CArrayPakBase::InsertL(Count(),&aRef,aLength);} + + + + +template +inline T &CArrayPak::ExpandL(TInt anIndex,TInt aLength) +/** +Expands the array by one element of specified length at the specified position. + +It: + +1. expands the array by one element at the specified position. + +2. constructs a new element of specified length at that position. + +3. returns a reference to the new element. + +All existing elements from position anIndex to the end of the array are moved +up, so that the element originally at position anIndex is now at position +anIndex + 1 etc. + +The new element of type and length aLength is constructed at position +anIndex, using the default constructor of that class. + +@param anIndex The position within the array where the array is to be expanded + and the new object is to be constructed. +@param aLength The length of the new element. + +@return A reference to the newly constructed object at position + anIndex within the array. + +@leave KErrNoMemory The function attempted to allocate from the heap and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. + +@panic E32USER-CBase 21, if anIndex is negative or greater than the number of + elements currently in the array. +@panic E32USER-CBase 30, if aLength is negative. +*/ + {return(*new(CArrayPakBase::ExpandL(anIndex,aLength)) T);} + + + + +template +inline T &CArrayPak::ExtendL(TInt aLength) +/** +Expands the array by one element of specified length at the end of the array. + +It: + +1. expands the array by one element at the end of the array, i.e. at position + CArrayPakbase::Count(). + +2. constructs a new element of length aLength at that position. + +3. returns a reference to the new element. + +The new element of type is constructed at the end of the array, +using the default constructor of that class. + +@param aLength The length of the new element. + +@return A reference to the newly constructed object at the end of + the array. + +@leave KErrNoMemory The function attempted to allocate from the heap and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. + +@panic E32USER-CBase 30, if aLength is negative. +*/ + {return(*new(CArrayPakBase::ExpandL(Count(),aLength)) T);} + + + + +template +inline TInt CArrayPak::Find(const T &aRef,TKeyArrayPak &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a sequential search. + +The array is searched sequentially for an element whose key matches the key +of the supplied object. The search starts with the first element +in the array. + +Note that where an array has elements with duplicate keys, the function only +supplies the position of the first element in the array with that key. + +@param aRef A reference to an object of type whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A reference to a TInt supplied by the caller. On return, if the + element is found, this 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 or the array is empty, then this is undefined. + +@return Zero, if the element with the specified key is found. Non-zero, if + the element with the specified key is not found. +*/ + {return(CArrayPakBase::Find(&aRef,aKey,anIndex));} + + + + +template +inline TInt CArrayPak::FindIsq(const T &aRef,TKeyArrayPak &aKey,TInt &anIndex) const +/** +Finds the position of an element within the array, based on the matching of +keys, using a binary search technique. + +The array is searched, using a binary search technique, for an element whose +key matches the key of the supplied object. + +The array must be in key order. + +Note that where an array has elements with duplicate keys, the function cannot +guarantee which element, with the given key value, it will return, except that it +will find one of them. + +@param aRef A reference to an object of type whose key is used + for comparison. +@param aKey A reference to a key object defining the properties of the key. +@param anIndex A reference to a TInt supplied by the caller. On return, if the + element is found, this 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 + this is set to the position of the first element in the array + with a key which is greater than the key of the object aRef. + If the element is not found and the array is empty, then this + is undefined. + +@return Zero, if the element with the specified key is found or the array is + empty. + Non-zero, if the element with the specified key is not found. +*/ + {return(CArrayPakBase::FindIsq(&aRef,aKey,anIndex));} + + + + +template +inline void CArrayPak::InsertL(TInt anIndex,const T &aRef,TInt aLength) +/** +Inserts an element of a specified length into the array at the specified +position. + +@param anIndex The position within the array where the element is to be + inserted. The position is relative to zero, i.e. zero implies + that elements are inserted at the beginning of the array. +@param aRef A reference to the class T object to be inserted into + the array. +@param aLength The length of the element to be inserted into the array. + +@leave KErrNoMemory The function attempted to expand the array buffer and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. + +@panic E32USER-CBase 21, if anIndex is negative or greater than the number of + objects currently in the array. +@panic E32USER-CBase 30, if aLength is negative. +*/ + {CArrayPakBase::InsertL(anIndex,&aRef,aLength);} + + + + +template +inline TInt CArrayPak::InsertIsqL(const T &aRef,TInt aLength,TKeyArrayPak &aKey) +/** +Inserts a single element of a specified length into the array at a position +determined by a key. + +The array MUST already be in key sequence (as defined by the key), otherwise +the position of the new element is unpredictable, or duplicates may occur. + +Elements with duplicate keys are not permitted. + +@param aRef A reference to the element of type to be inserted into + the array. +@param aLength The length of the new element of type to be inserted + into the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrAlreadyExists An element with the same key already exists within + the array. NB the array MUST already be in key sequence, otherwise + the function may insert a duplicate and fail to leave with + this value. +@leave KErrNoMemory The function attempted to expand the array buffer and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. +*/ + {return(CArrayPakBase::InsertIsqL(&aRef,aLength,aKey));} + + + + +template +inline TInt CArrayPak::InsertIsqAllowDuplicatesL(const T &aRef,TInt aLength,TKeyArrayPak &aKey) +/** +Inserts a single element of a specified length into the array at a position +determined by a key, allowing duplicates. + +The array MUST already be in key sequence, otherwise the position of the +new element is unpredictable. + +Elements with duplicate keys are permitted. If the new element's key is a +duplicate of an existing element's key, then the new element is positioned +after the existing element. + +@param aRef A reference to the element of type to be inserted into + the array. +@param aLength The length of the new element to be inserted into the array. +@param aKey A reference to a key object defining the properties of the key. + +@return The position within the array of the newly inserted element. + +@leave KErrNoMemory The function attempted to expand the array buffer and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. +*/ + {return(CArrayPakBase::InsertIsqAllowDuplicatesL(&aRef,aLength,aKey));} + + + + +template +inline const TArray CArrayPak::Array() const +/** +Constructs and returns a TArray object. + +@return A Tarray object for this array. +*/ + {return(TArray(CountR,AtR,this));} + + + + +inline CArrayPak::CArrayPak(TBufRep aRep,TInt aGranularity) + : CArrayPakBase(aRep,aGranularity) +/** +Constructs a variable array with the specified granularity and +buffer organisation. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aRep A pointer to a function used to expand the array buffer. + The organisation of the array buffer is implied by the + choice of this function. + For a flat array buffer, pass (TBufRep)CBufFlat::NewL. + For a segmented array buffer, pass (TBufRep)CBufSeg::NewL. +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 19, if aGranularity is not positive. +*/ + {} + + + + +inline const TAny *CArrayPak::At(TInt anIndex) const +/** +Gets a pointer to the untyped element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where that reference cannot be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A pointer to the const element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayPakBase::At(anIndex));} + + + + +inline TAny *CArrayPak::At(TInt anIndex) +/** +Gets a pointer to the untyped element located at the specified position +within the array. + +The compiler uses this variant of the function if the returned reference is +used in an expression where that reference can be modified. + +@param anIndex The position of the element within the array, relative to zero; + i.e. zero implies the first element. + +@return A pointer to the non-const element located at position anIndex within + the array. + +@panic E32USER-CBase 21, if anIndex is negative or greater than or equal to + the number of objects currently within the array. +*/ + {return(CArrayPakBase::At(anIndex));} + + + + +inline void CArrayPak::AppendL(const TAny *aPtr,TInt aLength) +/** +Appends the untyped element of the specified length onto the end of the array. + +@param aPtr A pointer to an untyped element to be appended. +@param aLength The length of the untyped element. + +@leave KErrNoMemory The function attempted to expand the array buffer and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. +*/ + {CArrayPakBase::InsertL(Count(),aPtr,aLength);} + + + + +inline TAny *CArrayPak::ExtendL(TInt aLength) +/** +Expands the array by one element of the specified length at the end of +the array, and returns a pointer to this new location. + +As elements are untyped, no construction is possible and the content of +the new location remains undefined. + +@param aLength The length of the new element. + +@return A pointer to the new element location at the end of the array. + +@leave KErrNoMemory The function attempted to expand the array buffer and there + is insufficient memory available. In this case, the array is left in the + state it was in before the call. +*/ + {return(CArrayPakBase::ExpandL(Count(),aLength));} + + + + +// Template class CArrayPakFlat +template +inline CArrayPakFlat::CArrayPakFlat(TInt aGranularity) + : CArrayPak((TBufRep)CBufFlat::NewL,aGranularity) +/** +Constructs a packed flat array with specified granularity. + +Note that no memory is allocated to the array buffer by this constructor. + +@param aGranularity The granularity of the array. + +@panic E32USER-CBase 20, if aGranularity is not positive. +*/ + {} + + + + +// Class CObject +inline TInt CObject::UniqueID() const +/** +Gets this reference counting object's unique ID. + +The unique ID is an integer which is a property of the object container. It +forms part of the identity of all reference counting objects and is the same +value for all reference counting objects held within the same object container. + +@return This reference counting object's unique ID. + +@see CObjectCon +*/ + {return(iContainer->UniqueID());} + + + + +inline TInt CObject::AccessCount() const +/** +Gets the number of open references to this reference counting object. + +@return The number of open references. +*/ + {return(iAccessCount);} + + + + +inline void CObject::Inc() +/** +Adds one to the reference count. + +This function is called by the default implementation of the Open() member +function of this class. + +@see CObject::Open +*/ + {iAccessCount++;} + + + + +inline void CObject::Dec() +/** +Subtracts one from the reference count. + +This function is called by the default implementation of the Close() member +function of this class. + +@see CObject::Close +*/ + {iAccessCount--;} + + + + +inline CObject * CObject::Owner() const +/** +Gets a pointer to the reference counting object which owns this +reference counting object. + +@return A pointer to the owning reference counting object. This is NULL, if + there is no owner. +*/ + {return(iOwner);} + + + + +inline void CObject::SetOwner(CObject *anOwner) +/** +Sets the owner of this reference counting object. + +If this reference counting object already has an owner, then all knowledge +of that owner is lost. + +@param anOwner A pointer to the reference counting object which is to be the + new owner of this reference counting object. +*/ + {iOwner=anOwner;} + + + + +// class CObjectIx +inline TInt CObjectIx::Count() const +/** +Gets the number greater then the last slot number used to hold valid CObject pointer. +The input argument of CObject* CObjectIx::operator[]() must be less then the number returned by this method. + +@return The number greater then the last used slot. + +@see CObjectIx::ActiveCount +@see CObjectIx::operator[] +*/ + {return iHighWaterMark;} + + + + +inline TInt CObjectIx::ActiveCount() const +/** +Gets the current number of reference counting objects held by this +object index. + +@return The current number. +*/ + {return iNumEntries;} + + + +// class CObjectCon +inline TInt CObjectCon::UniqueID() const +/** +Gets this object container's unique ID. + +@return The unique ID value. +*/ + {return iUniqueID;} + + + + +inline TInt CObjectCon::Count() const +/** +Gets the number of reference counting objects in this object container. + +@return The number of objects. +*/ + {return iCount;} + + + + + +// class CCirBufBase +inline TInt CCirBufBase::Count() const +/** +Gets the current number of objects in this circular buffer. + +@return The number of objects in this circular buffer. + This value can never be greater than the maximum capacity. +*/ + {return(iCount);} + + + + +inline TInt CCirBufBase::Length() const +/** +Gets the maximum capacity of this circular buffer. + +The capacity is the maximum number of elements that the buffer can hold. + +Use SetLengthL() to change the capacity of the circular buffer. + +@return The maximum capacity of this circular buffer. + +@see CCirBufBase::SetLengthL +*/ + {return(iLength);} + + + + +// Template class CCirBuf +template +inline CCirBuf::CCirBuf() + : CCirBufBase(sizeof(T)) +/** +Default C++ constructor. + +The size of each object in the buffer is fixed and is the length of the class +passed as the template parameter. + +@panic E32USER-CBase 72, if the length of the template class is zero. +*/ + {} + + + + +template +inline TInt CCirBuf::Add(const T *aPtr) +/** +Adds a single object to the circular buffer. + +The object is of type class T and is only added if there is space available. + +@param aPtr A pointer to the object of type class T to be added to the circular + buffer. + +@return 1 if the object is successfully added. 0 if the object cannot be added + because the circular buffer is full. + +@panic E32USER-CBase 74, if a call to CCirBufBase::SetLengthL() has not been + made before calling this function. + +@see CCirBufBase::SetLengthL +*/ + {return(DoAdd((const TUint8 *)aPtr));} + + + + +template +inline TInt CCirBuf::Add(const T *aPtr,TInt aCount) +/** +Adds multiple objects to the circular buffer. + +The function attempts to add aCount objects of type class T. The objects are +only added if there is space available. + +@param aPtr A pointer to a set of contiguous objects of type class T to be + added to the circular buffer. + +@param aCount The number of objects to be added to the circular buffer. + +@return The number of objects successfully added to the buffer. This value + may be less than the number requested and can range from 0 to aCount. + +@panic E32USER-CBase 74, if a call to CCirBufBase::SetLengthL() has not been + made before calling this function. +@panic E32USER-CBase 75, if aCount is not a positive value. + +@see CCirBufBase::SetLengthL +*/ + {return(DoAdd((const TUint8 *)aPtr,aCount));} + + + + +template +inline TInt CCirBuf::Remove(T *aPtr) +/** +Removes a single object from the circular buffer. + +An object can only be removed if there are objects in the buffer. + +A binary copy of the object is made to aPtr. + +@param aPtr A pointer to an object of type class T supplied by the caller. + +@return 1 if an object is successfully removed. 0 if an object cannot be removed + because the circular buffer is empty. +*/ + {return(DoRemove((TUint8 *)aPtr));} + + + + +template +inline TInt CCirBuf::Remove(T *aPtr,TInt aCount) +/** +Removes multiple objects from the circular buffer. + +The function attempts to remove aCount objects of type class T. +Objects can only be removed if there are objects in the buffer + +A binary copy of the objects is made to aPtr. + +@param aPtr A pointer to contiguous memory able to hold aCount class T objects, + supplied by the caller. + +@param aCount The number of objects to be removed from the circular buffer. + +@return The number of objects successfully removed from the buffer. This value + may be less than the number requested, and can range from 0 to aCount. + +@panic E32USER-CBase 76, if aCount is not a positive value. +*/ + {return(DoRemove((TUint8 *)aPtr,aCount));} + + + + +// Class CActive +inline TBool CActive::IsActive() const +/** +Determines whether the active object has a request outstanding. + +A request is outstanding when: + +1. it has been issued + +2. it has not been cancelled + +3. it servicing has not yet begun. + +@return True, if a request is outstanding; false, otherwise. +*/ + {return(iStatus.iFlags&TRequestStatus::EActive);} + + + + +inline TBool CActive::IsAdded() const +/** +Determines whether the active object has been added to the active scheduler's +list of active objects. + +If the active object has not been added to a scheduler, it cannot handle the +completion of any request. No request should be issued until the active object +has been added to a scheduler because completion of that request generates +what appears to be a stray signal. + +Use the active object function Deque() to remove the active object from the +scheduler. + +@return True, if the active object has been added to an active scheduler; + false, otherwise. + +@see CActive::Deque +*/ + {return(iLink.iNext!=NULL);} + + + + +inline TInt CActive::Priority() const +/** +Gets the priority of the active object. + +@return The active object's priority value. +*/ + {return iLink.iPriority;} + + + + +// class CDeltaTimer +inline TDeltaTimerEntry::TDeltaTimerEntry(TCallBack& aCallback) +/** +Constructor specifying a general callback. + +@param aCallback The callback to be called when this timed event entry expires. +*/ + {iCallBack=aCallback;} + + + + +inline TDeltaTimerEntry::TDeltaTimerEntry() +/** +Default constructor. +*/ + {} + + + + +inline void TDeltaTimerEntry::Set(TCallBack& aCallback) +/** +Sets the specified callback. + +@param aCallback The callback to be called when this timed event entry expires. +*/ + {iCallBack=aCallback;} + + + + +/** +Gets a reference to the server's current message. + +@return The current message that contains the client request details. +*/ +inline const RMessage2 &CServer2::Message() const + {return iMessage;} + + + + +/** +Gets the server active object that handles messages for this session. + +This is the instance of the CServer2 derived class that created +this session object. + +@return The server active object. +*/ +inline const CServer2 *CSession2::Server() const + {return iServer;} + + + + +// Class CAsyncOneShot +inline RThread& CAsyncOneShot::Thread() +/** +Gets a handle to the current thread. + +@return The handle to the current thread. +*/ + { return iThread; } + + + + +// Class CActiveScheduler +inline TInt CActiveScheduler::Level() const +/** +@deprecated Use the StackDepth() function instead. + +Gets the scheduler's level of nestedness. + +@return The level of nestedness. + +@see StackDepth() +*/ + {return StackDepth();} + + + + +// Class CActiveSchedulerWait +inline TBool CActiveSchedulerWait::IsStarted() const +/** +Reports whether this CActiveSchedulerWait object is currently started. + +Note: a CActiveSchedulerWait object itself becomes "stopped" as +soon as AsyncStop() is called, and can be started again immediately if +required (but this would start a new nested level of the scheduler). + +@return True if the scheduling loop is active; false, otherwise. + +@see CActiveSchedulerWait::Start +@see CActiveSchedulerWait::AsyncStop +*/ + {return iLoop != NULL;} + + + + +// Class CleanupStack +#ifdef _DEBUG +inline void CleanupStack::Pop(TAny* aExpectedItem) +/** +Pops an object from the top of the cleanup stack. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function checks that the specified item is at the top + of the cleanup stack before attempting to pop it; an E32USER-CBase 90 panic + is raised if the check fails. + +2 In a release build, the function just pops the object which is at the top + of the cleanup stack; no checking is done. + +@param aExpectedItem A pointer to the item expected to be at the top of the + cleanup stack. In a release build, this parameter + is not used. +*/ + { CleanupStack::Check(aExpectedItem); CleanupStack::Pop(); } + + + + +inline void CleanupStack::Pop(TInt aCount, TAny* aLastExpectedItem) +/** +Pops the specified number of objects from the top of the cleanup stack. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function pops (aCount-1) items from the cleanup stack, + and then checks that the specified item is the next one on the cleanup stack + before attempting to pop it; an E32USER-CBase 90 panic is raised if the + check fails. + +2. In a release build, the function just pops aCount items from the cleanup stack; + no checking is done. + +@param aCount The number of items top be popped from + the cleanup stack. +@param aLastExpectedItem A pointer to the item expected to be at the top of + the cleanup stack, after (aCount-1) items have been + popped. In a release build, this parameter is + not used. +*/ + { + if (--aCount) + CleanupStack::Pop(aCount); + CleanupStack::Check(aLastExpectedItem); + CleanupStack::Pop(); + } + + + + +inline void CleanupStack::PopAndDestroy(TAny* aExpectedItem) +/** +Pops an object from the top of the cleanup stack, and cleans it up. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function checks that the specified item is at the top + of the cleanup stack before attempting to pop and clean it up; + an E32USER-CBase 90 panic is raised if the check fails. + +2. In a release build, the function just pops and cleans up the object at + the top of the cleanup stack; no checking is done. + +@param aExpectedItem A pointer to the item expected to be at the top of the + cleanup stack. In a release build, this parameter is + not used. +*/ + { CleanupStack::Check(aExpectedItem); CleanupStack::PopAndDestroy(); } + + + + +inline void CleanupStack::PopAndDestroy(TInt aCount, TAny* aLastExpectedItem) +/** +Pops the specified number of objects from the top of the cleanup stack, and +cleans them up. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function pops and cleans up (aCount-1) items from the + cleanup stack, and then checks that the specified item is the next one on + the cleanup stack before attempting to pop it and clean it up; + an E32USER-CBase 90 panic is raised if the check fails. + +2. In a release build, the function just pops and cleans up aCount items from + the cleanup stack; no checking is done. + +@param aCount The number of items top be popped from the + cleanup stack, and cleaned up. +@param aLastExpectedItem A pointer to the item expected to be at the top of + the cleanup stack, after (aCount-1) items have been + popped and cleaned up. In a release build, this + parameter is not used. +*/ + { + if (--aCount) + CleanupStack::PopAndDestroy(aCount); + CleanupStack::Check(aLastExpectedItem); + CleanupStack::PopAndDestroy(); + } +#else +inline void CleanupStack::Pop(TAny*) +/** +Pops an object from the top of the cleanup stack. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function checks that the specified item is at the top + of the cleanup stack before attempting to pop it; an E32USER-CBase 90 panic + is raised if the check fails. + +2 In a release build, the function just pops the object which is at the top + of the cleanup stack; no checking is done. + +@param aExpectedItem A pointer to the item expected to be at the top of the + cleanup stack. In a release build, this parameter + is not used. +*/ + { CleanupStack::Pop(); } + + + + +inline void CleanupStack::Pop(TInt aCount, TAny*) +/** +Pops the specified number of objects from the top of the cleanup stack. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function pops (aCount-1) items from the cleanup stack, + and then checks that the specified item is the next one on the cleanup stack + before attempting to pop it; an E32USER-CBase 90 panic is raised if the + check fails. + +2. In a release build, the function just pops aCount items from the cleanup stack; + no checking is done. + +@param aCount The number of items top be popped from + the cleanup stack. +@param aLastExpectedItem A pointer to the item expected to be at the top of + the cleanup stack, after (aCount-1) items have been + popped. In a release build, this parameter is + not used. +*/ + { CleanupStack::Pop(aCount); } + + + + +inline void CleanupStack::PopAndDestroy(TAny*) +/** +Pops an object from the top of the cleanup stack, and cleans it up. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function checks that the specified item is at the top + of the cleanup stack before attempting to pop and clean it up; + an E32USER-CBase 90 panic is raised if the check fails. + +2. In a release build, the function just pops and cleans up the object at + the top of the cleanup stack; no checking is done. + +@param aExpectedItem A pointer to the item expected to be at the top of the + cleanup stack. In a release build, this parameter is + not used. +*/ + { CleanupStack::PopAndDestroy(); } + + + + +inline void CleanupStack::PopAndDestroy(TInt aCount, TAny*) +/** +Pops the specified number of objects from the top of the cleanup stack, and +cleans them up. + +The function has two modes of operation, depending on whether it is part of +a debug build or a release build. + +1. In a debug build, the function pops and cleans up (aCount-1) items from the + cleanup stack, and then checks that the specified item is the next one on + the cleanup stack before attempting to pop it and clean it up; + an E32USER-CBase 90 panic is raised if the check fails. + +2. In a release build, the function just pops and cleans up aCount items from + the cleanup stack; no checking is done. + +@param aCount The number of items top be popped from the + cleanup stack, and cleaned up. +@param aLastExpectedItem A pointer to the item expected to be at the top of + the cleanup stack, after (aCount-1) items have been + popped and cleaned up. In a release build, this + parameter is not used. +*/ + { CleanupStack::PopAndDestroy(aCount); } +#endif + + + + +// Class TCleanupItem +inline TCleanupItem::TCleanupItem(TCleanupOperation anOperation) + : iOperation(anOperation) +/** +Constructs the object with a cleanup operation. + +@param anOperation A cleanup operation which will be invoked by the pop and + destroy action resulting from a subsequent call to + CleanupStack::PopAndDestroy(). +*/ + {} + + + + +inline TCleanupItem::TCleanupItem(TCleanupOperation anOperation,TAny *aPtr) + : iOperation(anOperation), iPtr(aPtr) +/** +Constructs the object with a cleanup operation and a pointer to the object +to be cleaned up. + +@param anOperation A cleanup operation which will be invoked by the pop + and destroy action resulting from a subsequent call to + CleanupStack::PopAndDestroy(). + +@param aPtr A pointer to an object which is the target of the + cleanup operation. +*/ + {} + + + + +// Class TCleanupTrapHandler +inline CCleanup &TCleanupTrapHandler::Cleanup() + {return(*iCleanup);} + +// Class TAutoClose +template +inline TAutoClose::~TAutoClose() +/** +Destructor. + +The implementation calls Close() on iObj, the instance of the template class. +*/ +#ifdef __LEAVE_EQUALS_THROW__ + {if (!std::uncaught_exception()) iObj.Close();} +#else + {iObj.Close();} +#endif + + + + +template +inline void TAutoClose::PushL() +/** +Pushes a cleanup item onto the cleanup stack, so that Close() is called on the +templated class object, iObj, if a leave occurs. +*/ + {CleanupStack::PushL(TCleanupItem(Close, (TAny *)&iObj));} + + + + +template +inline void TAutoClose::Pop() +/** +Pops a single cleanup item from the cleanup stack. +*/ + {CleanupStack::Pop();} + + + + +template +void TAutoClose::Close(TAny *aObj) + {((T *)aObj)->Close();} + + + + +// Template class CleanupDelete +template +inline void CleanupDelete::PushL(T* aPtr) +/** +Creates a TCleanupItem for the specified object. + +The cleanup operation is the private static function Delete() of this class, which +deletes the specified object. + +@param aPtr The object for which a TCleanupItem is to be constructed. +*/ + {CleanupStack::PushL(TCleanupItem(&Delete,aPtr));} + + + + +template +void CleanupDelete::Delete(TAny *aPtr) +/** +The cleanup operation to be performed. + +@param aPtr A pointer to the object for which clean up is to be performed. + The implementation deletes this object. +*/ + {delete STATIC_CAST(T*,aPtr);} + + + + +// See header file e32base.h for in-source comment. +template +inline void CleanupDeletePushL(T* aPtr) + {CleanupDelete::PushL(aPtr);} + + + + +// Template class CleanupArrayDelete +template +inline void CleanupArrayDelete::PushL(T* aPtr) +/** +Creates a TCleanupItem for the specified array. + +The cleanup operation is the private static function ArrayDelete() of +this class, which deletes the specified array. + +@param aPtr The array of class T type objects for which a TCleanupItem is + to be constructed. +*/ + {CleanupStack::PushL(TCleanupItem(&ArrayDelete,aPtr));} + + + + +template +void CleanupArrayDelete::ArrayDelete(TAny *aPtr) +/** +The cleanup operation to be performed. + +@param aPtr A pointer to the array for which clean up is to be performed. + The implementation deletes this array. +*/ + {delete [] STATIC_CAST(T*,aPtr);} + + + + +// See header file e32base.h for in-source comment. +template +inline void CleanupArrayDeletePushL(T* aPtr) + {CleanupArrayDelete::PushL(aPtr);} + + + + +// Template class CleanupClose +template +inline void CleanupClose::PushL(T& aRef) +/** +Creates a TCleanupItem for the specified object. + +The cleanup operation is the private static function Close() of this class. + +@param aRef The object for which a TCleanupItem is to be constructed. +*/ + {CleanupStack::PushL(TCleanupItem(&Close,&aRef));} + + + + +template +void CleanupClose::Close(TAny *aPtr) +/** +The cleanup operation to be performed. + +@param aPtr A pointer to the object for which clean up is to be performed. + The implementation calls Close() on this object. +*/ + {(STATIC_CAST(T*,aPtr))->Close();} + + + + +// See header file e32base.h for in-source comment. +template +inline void CleanupClosePushL(T& aRef) + {CleanupClose::PushL(aRef);} + + + + +// Template class CleanupRelease +template +inline void CleanupRelease::PushL(T& aRef) +/** +Creates a TCleanupItem for the specified object. + +The cleanup operation is the private static function Release() of this class. + +@param aRef The object for which a TCleanupItem is to be constructed. +*/ + {CleanupStack::PushL(TCleanupItem(&Release,&aRef));} + + + + +template +void CleanupRelease::Release(TAny *aPtr) +/** +The cleanup operation to be performed. + +@param aPtr A pointer to the object for which clean up is to be performed. + The implementation calls Release() on this object. +*/ + {(STATIC_CAST(T*,aPtr))->Release();} + + + + +// See header file e32base.h for in-source comment. +template +inline void CleanupReleasePushL(T& aRef) + {CleanupRelease::PushL(aRef);} + + +