epoc32/include/e32des8.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     4
// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
// e32\include\e32des8.h
williamr@2
    15
// 
williamr@2
    16
//
williamr@2
    17
williamr@2
    18
#ifndef __E32DES8_H__
williamr@2
    19
#define __E32DES8_H__
williamr@2
    20
williamr@2
    21
/**
williamr@2
    22
@internalComponent
williamr@2
    23
*/
williamr@2
    24
const TUint KMaskDesLength8=0xfffffff;
williamr@2
    25
/**
williamr@2
    26
@internalComponent
williamr@2
    27
*/
williamr@2
    28
const TInt KShiftDesType8=28;
williamr@2
    29
williamr@2
    30
class TBufCBase8;
williamr@2
    31
class TDes8;
williamr@2
    32
class TPtrC8;
williamr@2
    33
class TPtr8;
williamr@2
    34
class TPtr16;
williamr@2
    35
#ifndef __KERNEL_MODE__
williamr@2
    36
class HBufC8;
williamr@2
    37
#endif
williamr@2
    38
class TDesC8
williamr@2
    39
/**
williamr@2
    40
@publishedAll
williamr@2
    41
@released
williamr@2
    42
williamr@2
    43
Abstract base class for 8-bit non-modifiable descriptors.
williamr@2
    44
williamr@2
    45
The class encapsulates the data member containing the length of data
williamr@2
    46
represented by an 8-bit descriptor. It also provides member functions through
williamr@2
    47
which the data can be accessed, but not modified.
williamr@2
    48
williamr@2
    49
Data represented by this class is treated as a contiguous set of 8-bit (i.e. 
williamr@2
    50
single byte) values or data items.
williamr@2
    51
williamr@2
    52
This class cannot be instantiated as it is intended to form part of a class 
williamr@2
    53
hierarchy; it provides a well defined part of descriptor behaviour. It can, 
williamr@2
    54
however, be passed as an argument type for functions which want access to 
williamr@2
    55
descriptor data but do not need to modify that data.
williamr@2
    56
williamr@2
    57
@see TDesC
williamr@2
    58
@see TPtrC8
williamr@2
    59
*/
williamr@2
    60
    {
williamr@2
    61
public:
williamr@2
    62
	inline TBool operator<(const TDesC8 &aDes) const;
williamr@2
    63
	inline TBool operator<=(const TDesC8 &aDes) const;
williamr@2
    64
	inline TBool operator>(const TDesC8 &aDes) const;
williamr@2
    65
	inline TBool operator>=(const TDesC8 &aDes) const;
williamr@2
    66
	inline TBool operator==(const TDesC8 &aDes) const;
williamr@2
    67
	inline TBool operator!=(const TDesC8 &aDes) const;
williamr@2
    68
	inline const TUint8 &operator[](TInt anIndex) const;
williamr@2
    69
	inline TInt Length() const;
williamr@2
    70
	inline TInt Size() const;
williamr@2
    71
	IMPORT_C const TUint8 *Ptr() const;
williamr@2
    72
	IMPORT_C TInt Compare(const TDesC8 &aDes) const;
williamr@2
    73
	IMPORT_C TInt Match(const TDesC8 &aDes) const;
williamr@2
    74
	IMPORT_C TInt MatchF(const TDesC8 &aDes) const;
williamr@2
    75
	IMPORT_C TInt MatchC(const TDesC8 &aDes) const;
williamr@2
    76
	IMPORT_C TInt Locate(TChar aChar) const;
williamr@2
    77
	IMPORT_C TInt LocateReverse(TChar aChar) const;
williamr@2
    78
	IMPORT_C TInt Find(const TDesC8 &aDes) const;
williamr@2
    79
	IMPORT_C TInt Find(const TUint8 *pS,TInt aLenS) const;
williamr@2
    80
	IMPORT_C TPtrC8 Left(TInt aLength) const;
williamr@2
    81
	IMPORT_C TPtrC8 Right(TInt aLength) const;
williamr@2
    82
	IMPORT_C TPtrC8 Mid(TInt aPos) const;
williamr@2
    83
	IMPORT_C TPtrC8 Mid(TInt aPos,TInt aLength) const;
williamr@2
    84
	IMPORT_C TInt CompareF(const TDesC8 &aDes) const;
williamr@2
    85
#ifndef __KERNEL_MODE__
williamr@2
    86
	IMPORT_C TInt CompareC(const TDesC8 &aDes) const;
williamr@2
    87
	IMPORT_C TInt LocateF(TChar aChar) const;
williamr@2
    88
	IMPORT_C TInt LocateReverseF(TChar aChar) const;
williamr@2
    89
	IMPORT_C TInt FindF(const TDesC8 &aDes) const;
williamr@2
    90
	IMPORT_C TInt FindF(const TUint8 *pS,TInt aLenS) const;
williamr@2
    91
	IMPORT_C TInt FindC(const TDesC8 &aDes) const;
williamr@2
    92
	IMPORT_C TInt FindC(const TUint8 *pS,TInt aLenS) const;
williamr@2
    93
	IMPORT_C HBufC8 *Alloc() const;
williamr@2
    94
	IMPORT_C HBufC8 *AllocL() const;
williamr@2
    95
	IMPORT_C HBufC8 *AllocLC() const;
williamr@2
    96
#endif
williamr@2
    97
protected:
williamr@2
    98
	inline TDesC8(TInt aType,TInt aLength);
williamr@2
    99
	inline TDesC8() {}
williamr@2
   100
// delay this for a while
williamr@2
   101
#ifdef SYMBIAN_FIX_TDESC_CONSTRUCTORS
williamr@2
   102
	inline TDesC8( const TDesC8& aOther) : iLength(aOther.iLength) {}
williamr@2
   103
#endif
williamr@2
   104
//	inline ~TDesC8() {}			Commented out for the moment since it breaks code
williamr@2
   105
	inline TInt Type() const;
williamr@2
   106
	inline void DoSetLength(TInt aLength);
williamr@2
   107
	IMPORT_C const TUint8 &AtC(TInt anIndex) const;
williamr@2
   108
private:
williamr@2
   109
	TUint iLength;
williamr@2
   110
	__DECLARE_TEST;
williamr@2
   111
    };
williamr@2
   112
//
williamr@2
   113
class TPtrC8 : public TDesC8
williamr@2
   114
/**
williamr@2
   115
@publishedAll
williamr@2
   116
@released
williamr@2
   117
williamr@2
   118
8-bit non-modifiable pointer descriptor.
williamr@2
   119
williamr@2
   120
This is a descriptor class intended for instantiation and encapsulates a
williamr@2
   121
pointer to the 8-bit data that it represents. The data can live in ROM or RAM
williamr@2
   122
and this location is separate from the descriptor object itself.
williamr@2
   123
williamr@2
   124
The data is intended to be accessed, but not changed, through this descriptor. 
williamr@2
   125
The base class provides the functions through which data is accessed.
williamr@2
   126
williamr@2
   127
@see TPtr8
williamr@2
   128
@see TDesC8
williamr@2
   129
@see TDes8
williamr@2
   130
@see TBufC8
williamr@2
   131
@see TBuf8
williamr@2
   132
@see HBufC8
williamr@2
   133
*/
williamr@2
   134
	{
williamr@2
   135
public:
williamr@2
   136
	IMPORT_C TPtrC8();
williamr@2
   137
	IMPORT_C TPtrC8(const TDesC8 &aDes);
williamr@2
   138
	IMPORT_C TPtrC8(const TUint8 *aString);
williamr@2
   139
	IMPORT_C TPtrC8(const TUint8 *aBuf,TInt aLength);
williamr@2
   140
	inline void Set(const TUint8 *aBuf,TInt aLength);
williamr@2
   141
	inline void Set(const TDesC8 &aDes);
williamr@2
   142
	inline void Set(const TPtrC8& aPtr);
williamr@2
   143
private:
williamr@2
   144
	TPtrC8& operator=(const TPtrC8 &aDes);
williamr@2
   145
protected:
williamr@2
   146
	const TUint8 *iPtr;
williamr@2
   147
private:
williamr@2
   148
	__DECLARE_TEST;
williamr@2
   149
	};
williamr@2
   150
//
williamr@2
   151
class TDes8Overflow
williamr@2
   152
/**
williamr@2
   153
@publishedAll
williamr@2
   154
@released
williamr@2
   155
williamr@2
   156
An interface that defines an overflow handler for an 8-bit descriptor.
williamr@2
   157
williamr@2
   158
The interface encapsulates a function that is called when an attempt to append 
williamr@2
   159
formatted text fails because the descriptor is already at its maximum length.
williamr@2
   160
williamr@2
   161
A derived class must provide an implementation for the Overflow() member
williamr@2
   162
function.
williamr@2
   163
williamr@2
   164
@see TDes8::AppendFormat
williamr@2
   165
*/
williamr@2
   166
	{
williamr@2
   167
public:
williamr@2
   168
    /**
williamr@2
   169
    Handles the overflow.
williamr@2
   170
    
williamr@2
   171
    This function is called when the TDes8::AppendFormat() variant that takes
williamr@2
   172
    an overflow handler argument, fails.
williamr@2
   173
	
williamr@2
   174
	@param aDes The 8-bit modifiable descriptor whose overflow results in the 
williamr@2
   175
	            call to this overflow handler.
williamr@2
   176
	*/
williamr@2
   177
	virtual void Overflow(TDes8 &aDes)=0;
williamr@2
   178
	};
williamr@2
   179
//
williamr@2
   180
class TDes8IgnoreOverflow : public TDes8Overflow
williamr@2
   181
/**
williamr@2
   182
@publishedAll
williamr@2
   183
@released
williamr@2
   184
williamr@2
   185
A derived class which provides an implementation for the Overflow() member function
williamr@2
   186
where truncation is required.
williamr@2
   187
williamr@2
   188
@see TDes16::AppendFormat
williamr@2
   189
*/
williamr@2
   190
	{
williamr@2
   191
public:
williamr@2
   192
	/**
williamr@2
   193
	Handles the overflow.
williamr@2
   194
	
williamr@2
   195
	This function is called when the TDes8::AppendFormat() 
williamr@2
   196
	variant that takes an overflow handler argument, fails.
williamr@2
   197
	
williamr@2
   198
	@param aDes The 8-bit modifiable descriptor whose overflow results in the 
williamr@2
   199
	            call to this overflow handler.
williamr@2
   200
	*/
williamr@2
   201
	IMPORT_C virtual void Overflow(TDes8 &aDes);
williamr@2
   202
	};
williamr@2
   203
//
williamr@2
   204
class TDesC16;
williamr@2
   205
class TRealFormat;
williamr@2
   206
class TDes8 : public TDesC8
williamr@2
   207
/** 
williamr@2
   208
@publishedAll
williamr@2
   209
@released
williamr@2
   210
williamr@2
   211
Abstract base class for 8-bit modifiable descriptors.
williamr@2
   212
williamr@2
   213
The class encapsulates the data member containing the maximum length of data
williamr@2
   214
represented by an 8-bit descriptor. It also provides member functions through
williamr@2
   215
which the data can be modified.
williamr@2
   216
williamr@2
   217
The class adds to the behaviour provided by TDesC8.
williamr@2
   218
williamr@2
   219
This class cannot be instantiated as it is intended to form part of a class 
williamr@2
   220
hierarchy; it provides a well defined part of descriptor behaviour. It can, 
williamr@2
   221
however, be passed as an argument type for functions which need to both modify 
williamr@2
   222
and access descriptor data.
williamr@2
   223
williamr@2
   224
@see TDes
williamr@2
   225
@see TDesC8
williamr@2
   226
@see TDesC16
williamr@2
   227
*/
williamr@2
   228
	{
williamr@2
   229
public:
williamr@2
   230
	inline TDes8& operator=(const TUint8 *aString);
williamr@2
   231
	inline TDes8& operator=(const TDesC8 &aDes);
williamr@2
   232
	inline TDes8& operator=(const TDes8 &aDes);
williamr@2
   233
	inline TInt MaxLength() const;
williamr@2
   234
	inline TInt MaxSize() const;
williamr@2
   235
	inline const TUint8 &operator[](TInt anIndex) const;
williamr@2
   236
	inline TUint8 &operator[](TInt anIndex);
williamr@2
   237
	inline TDes8 &operator+=(const TDesC8 &aDes);
williamr@2
   238
	IMPORT_C void Zero();
williamr@2
   239
 	IMPORT_C void SetLength(TInt aLength);
williamr@2
   240
 	IMPORT_C void SetMax();
williamr@2
   241
	IMPORT_C void Copy(const TDesC8 &aDes);
williamr@2
   242
	IMPORT_C void Copy(const TUint8 *aBuf,TInt aLength);
williamr@2
   243
	IMPORT_C void Copy(const TUint8 *aString);
williamr@2
   244
	IMPORT_C void Copy(const TDesC16 &aDes);
williamr@2
   245
	IMPORT_C void Append(TChar aChar);
williamr@2
   246
	IMPORT_C void Append(const TDesC8 &aDes);
williamr@2
   247
	IMPORT_C void Append(const TDesC16 &aDes);
williamr@2
   248
	IMPORT_C void Append(const TUint8 *aBuf,TInt aLength);
williamr@2
   249
	IMPORT_C void Fill(TChar aChar);
williamr@2
   250
	IMPORT_C void Fill(TChar aChar,TInt aLength);
williamr@2
   251
	IMPORT_C void FillZ();
williamr@2
   252
	IMPORT_C void FillZ(TInt aLength);
williamr@2
   253
	IMPORT_C void Num(TInt64 aVal);
williamr@2
   254
	IMPORT_C void Num(TUint64 aVal, TRadix aRadix);
williamr@2
   255
	IMPORT_C void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
williamr@2
   256
	IMPORT_C void AppendNum(TInt64 aVal);
williamr@2
   257
	IMPORT_C void AppendNum(TUint64 aVal, TRadix aRadix);
williamr@2
   258
	IMPORT_C void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
williamr@2
   259
#ifndef __KERNEL_MODE__
williamr@2
   260
	IMPORT_C TPtr8 LeftTPtr(TInt aLength) const;
williamr@2
   261
	IMPORT_C TPtr8 RightTPtr(TInt aLength) const;
williamr@2
   262
	IMPORT_C TPtr8 MidTPtr(TInt aPos) const;
williamr@2
   263
	IMPORT_C TPtr8 MidTPtr(TInt aPos,TInt aLength) const;
williamr@2
   264
	IMPORT_C const TUint8 *PtrZ();
williamr@2
   265
	IMPORT_C void CopyF(const TDesC8 &aDes);
williamr@2
   266
	IMPORT_C void CopyC(const TDesC8 &aDes);
williamr@2
   267
	IMPORT_C void CopyLC(const TDesC8 &aDes);
williamr@2
   268
	IMPORT_C void CopyUC(const TDesC8 &aDes);
williamr@2
   269
	IMPORT_C void CopyCP(const TDesC8 &aDes);
williamr@2
   270
	IMPORT_C void Swap(TDes8 &aDes);
williamr@2
   271
	IMPORT_C void AppendFill(TChar aChar,TInt aLength);
williamr@2
   272
	IMPORT_C void ZeroTerminate();
williamr@2
   273
	IMPORT_C void Fold();
williamr@2
   274
	IMPORT_C void Collate();
williamr@2
   275
	IMPORT_C void LowerCase();
williamr@2
   276
	IMPORT_C void UpperCase();
williamr@2
   277
	IMPORT_C void Capitalize();
williamr@2
   278
	IMPORT_C void Repeat(const TUint8 *aBuf,TInt aLength);
williamr@2
   279
	IMPORT_C void Repeat(const TDesC8 &aDes);
williamr@2
   280
	IMPORT_C void Trim();
williamr@2
   281
	IMPORT_C void TrimAll();
williamr@2
   282
	IMPORT_C void TrimLeft();
williamr@2
   283
	IMPORT_C void TrimRight();
williamr@2
   284
	IMPORT_C void Insert(TInt aPos,const TDesC8 &aDes);
williamr@2
   285
	IMPORT_C void Delete(TInt aPos,TInt aLength);
williamr@2
   286
	IMPORT_C void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes);
williamr@2
   287
	IMPORT_C void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
williamr@2
   288
	IMPORT_C void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
williamr@2
   289
	IMPORT_C void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);
williamr@2
   290
	IMPORT_C TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
williamr@2
   291
	IMPORT_C void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
williamr@2
   292
	IMPORT_C TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
williamr@2
   293
	IMPORT_C void AppendNumUC(TUint64 aVal,TRadix aRadix=EDecimal);
williamr@2
   294
	IMPORT_C void Format(TRefByValue<const TDesC8> aFmt,...);
williamr@2
   295
	IMPORT_C void FormatList(const TDesC8 &aFmt,VA_LIST aList);
williamr@2
   296
	IMPORT_C void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
williamr@2
   297
	IMPORT_C void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
williamr@2
   298
	IMPORT_C void AppendJustify(const TUint8 *aString,TInt aWidth,TAlign anAlignment,TChar aFill);
williamr@2
   299
	IMPORT_C void AppendJustify(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
williamr@2
   300
	IMPORT_C void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...);
williamr@2
   301
	IMPORT_C void AppendFormat(TRefByValue<const TDesC8> aFmt,...);
williamr@2
   302
	IMPORT_C void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL);
williamr@2
   303
	IMPORT_C TPtr16 Expand();
williamr@2
   304
	IMPORT_C void Collapse();
williamr@2
   305
#endif //__KERNEL_MODE__
williamr@2
   306
protected:
williamr@2
   307
	inline TDes8(TInt aType,TInt aLength,TInt aMaxLength);
williamr@2
   308
	inline TUint8 *WPtr() const;
williamr@2
   309
	inline TDes8() {}
williamr@2
   310
// delay this for a while
williamr@2
   311
#ifdef SYMBIAN_FIX_TDESC_CONSTRUCTORS
williamr@2
   312
	inline TDes8(const TDes8& aOther) : TDesC8(aOther), iMaxLength(aOther.iMaxLength) {}
williamr@2
   313
#endif
williamr@2
   314
	void DoAppendNum(TUint64 aVal, TRadix aRadix, TUint aA, TInt aW);
williamr@2
   315
	void DoPadAppendNum(TInt aLength, TInt aW, const TUint8* aBuf);
williamr@2
   316
protected:
williamr@2
   317
	TInt iMaxLength;
williamr@2
   318
	__DECLARE_TEST;
williamr@2
   319
    };
williamr@2
   320
//
williamr@2
   321
class TPtr8 : public TDes8
williamr@2
   322
/**
williamr@2
   323
@publishedAll
williamr@2
   324
@released
williamr@2
   325
williamr@2
   326
8-bit modifiable pointer descriptor.
williamr@2
   327
williamr@2
   328
This is a descriptor class intended for instantiation and encapsulates a
williamr@2
   329
pointer to the 8-bit data that it represents. The data can live in ROM or
williamr@2
   330
RAM and this location is separate from the descriptor object itself.
williamr@2
   331
williamr@2
   332
The data is intended to be accessed and modified through this descriptor. 
williamr@2
   333
The base classes provide the functions through which the data can be 
williamr@2
   334
manipulated.
williamr@2
   335
williamr@2
   336
@see TPtr
williamr@2
   337
@see TPtrC8
williamr@2
   338
@see TDesC8
williamr@2
   339
@see TDes8
williamr@2
   340
@see TBufC8
williamr@2
   341
@see TBuf8
williamr@2
   342
@see HBufC8
williamr@2
   343
*/
williamr@2
   344
	{
williamr@2
   345
public:
williamr@2
   346
	IMPORT_C TPtr8(TUint8 *aBuf,TInt aMaxLength);
williamr@2
   347
	IMPORT_C TPtr8(TUint8 *aBuf,TInt aLength,TInt aMaxLength);
williamr@2
   348
	inline TPtr8& operator=(const TUint8 *aString);
williamr@2
   349
	inline TPtr8& operator=(const TDesC8& aDes);
williamr@2
   350
	inline TPtr8& operator=(const TPtr8& aPtr);
williamr@2
   351
	inline void Set(TUint8 *aBuf,TInt aLength,TInt aMaxLength);
williamr@2
   352
	inline void Set(const TPtr8 &aPtr);
williamr@2
   353
private:
williamr@2
   354
	IMPORT_C TPtr8(TBufCBase8 &aLcb,TInt aMaxLength);
williamr@2
   355
protected:
williamr@2
   356
	TUint8 *iPtr;
williamr@2
   357
private:
williamr@2
   358
	friend class TBufCBase8;
williamr@2
   359
	__DECLARE_TEST;
williamr@2
   360
	};
williamr@2
   361
//
williamr@2
   362
class TBufCBase8 : public TDesC8
williamr@2
   363
/**
williamr@2
   364
@internalAll
williamr@2
   365
*/
williamr@2
   366
	{
williamr@2
   367
protected:
williamr@2
   368
	IMPORT_C TBufCBase8();
williamr@2
   369
	inline TBufCBase8(TInt aLength);
williamr@2
   370
	IMPORT_C TBufCBase8(const TUint8 *aString,TInt aMaxLength);
williamr@2
   371
	IMPORT_C TBufCBase8(const TDesC8 &aDes,TInt aMaxLength);
williamr@2
   372
	IMPORT_C void Copy(const TUint8 *aString,TInt aMaxLength);
williamr@2
   373
	IMPORT_C void Copy(const TDesC8 &aDes,TInt aMaxLength);
williamr@2
   374
	inline TPtr8 DoDes(TInt aMaxLength);
williamr@2
   375
	inline TUint8 *WPtr() const;
williamr@2
   376
	};
williamr@2
   377
//
williamr@2
   378
#ifndef __KERNEL_MODE__
williamr@2
   379
class RReadStream;
williamr@2
   380
class HBufC8 : public TBufCBase8
williamr@2
   381
/**
williamr@2
   382
@publishedAll
williamr@2
   383
@released
williamr@2
   384
williamr@2
   385
8-bit heap descriptor.
williamr@2
   386
williamr@2
   387
This is a descriptor class which provides a buffer of fixed length, allocated 
williamr@2
   388
on the heap, for containing and accessing data.
williamr@2
   389
williamr@2
   390
The class is intended for instantiation.
williamr@2
   391
williamr@2
   392
Heap descriptors have the important property that they can be made larger 
williamr@2
   393
or smaller, changing the size of the descriptor buffer. This is achieved by 
williamr@2
   394
reallocating the descriptor. Unlike the behaviour of dynamic buffers, 
williamr@2
   395
reallocation is not done automatically.
williamr@2
   396
williamr@2
   397
Data is intended to be accessed, but not modified; however, it can be 
williamr@2
   398
completely replaced using the assignment operators of this class. The base
williamr@2
   399
class (TDesC8) provides the functions through which the data is accessed.
williamr@2
   400
williamr@2
   401
The descriptor is hosted by a heap cell, and the 8-bit data that the
williamr@2
   402
descriptor represents is part of the descriptor object itself. The size of the
williamr@2
   403
cell depends on the requested maximum length of the descriptor buffer when the
williamr@2
   404
descriptor is created or re-allocated.
williamr@2
   405
williamr@2
   406
It is important to note that the size of the allocated cell, and, therefore, 
williamr@2
   407
the resulting maximum length of the descriptor, may be larger than requested 
williamr@2
   408
due to the way memory is allocated in Symbian OS. The amount by which this 
williamr@2
   409
may be rounded up depends on the platform and build type.
williamr@2
   410
williamr@2
   411
@see HBufC
williamr@2
   412
@see TPtr8
williamr@2
   413
@see TDesC8
williamr@2
   414
*/
williamr@2
   415
	{
williamr@2
   416
public:
williamr@2
   417
	IMPORT_C static HBufC8 *New(TInt aMaxLength);
williamr@2
   418
	IMPORT_C static HBufC8 *NewL(TInt aMaxLength);
williamr@2
   419
	IMPORT_C static HBufC8 *NewLC(TInt aMaxLength);
williamr@2
   420
	IMPORT_C static HBufC8 *NewMax(TInt aMaxLength);
williamr@2
   421
	IMPORT_C static HBufC8 *NewMaxL(TInt aMaxLength);
williamr@2
   422
	IMPORT_C static HBufC8 *NewMaxLC(TInt aMaxLength);
williamr@2
   423
	IMPORT_C static HBufC8 *NewL(RReadStream &aStream,TInt aMaxLength);
williamr@2
   424
	IMPORT_C static HBufC8 *NewLC(RReadStream &aStream,TInt aMaxLength);
williamr@2
   425
	IMPORT_C HBufC8& operator=(const TUint8 *aString);
williamr@2
   426
	IMPORT_C HBufC8& operator=(const TDesC8 &aDes);
williamr@2
   427
	inline HBufC8& operator=(const HBufC8 &aLcb);
williamr@2
   428
	IMPORT_C HBufC8 *ReAlloc(TInt aMaxLength);
williamr@2
   429
	IMPORT_C HBufC8 *ReAllocL(TInt aMaxLength);
williamr@2
   430
	IMPORT_C TPtr8 Des();
williamr@2
   431
private:
williamr@2
   432
	inline HBufC8(TInt aLength);
williamr@2
   433
private:
williamr@2
   434
	TText8 iBuf[1];
williamr@2
   435
	__DECLARE_TEST;
williamr@2
   436
	};
williamr@2
   437
#endif
williamr@2
   438
//
williamr@2
   439
/**
williamr@2
   440
@internalComponent
williamr@2
   441
*/
williamr@2
   442
#define __Size8 (sizeof(TInt)/sizeof(TInt8))
williamr@2
   443
/**
williamr@2
   444
@internalComponent
williamr@2
   445
*/
williamr@2
   446
#define __Align8(s) ((((s)+__Size8-1)/__Size8)*__Size8)
williamr@2
   447
//
williamr@2
   448
template <TInt S>
williamr@2
   449
class TBufC8 : public TBufCBase8
williamr@2
   450
/**
williamr@2
   451
@publishedAll
williamr@2
   452
@released
williamr@2
   453
williamr@2
   454
8-bit non-modifiable buffer descriptor. 
williamr@2
   455
williamr@2
   456
This is a descriptor class which provides a buffer of fixed length for
williamr@2
   457
containing and accessing TUint8 data.
williamr@2
   458
williamr@2
   459
The class intended for instantiation. The 8-bit data that the descriptor
williamr@2
   460
represents is part of the descriptor object itself. 
williamr@2
   461
williamr@2
   462
The class is templated, based on an integer value which defines the size of 
williamr@2
   463
the descriptor's data area.
williamr@2
   464
williamr@2
   465
The data is intended to be accessed, but not modified; however, it can be 
williamr@2
   466
completely replaced using the assignment operators of this class. The base 
williamr@2
   467
class provides the functions through which the data is accessed.
williamr@2
   468
williamr@2
   469
@see TBufC
williamr@2
   470
@see TDesC8
williamr@2
   471
@see TPtr8
williamr@2
   472
@see TUint8
williamr@2
   473
*/
williamr@2
   474
	{
williamr@2
   475
public:
williamr@2
   476
	inline TBufC8();
williamr@2
   477
    inline TBufC8(const TUint8 *aString);
williamr@2
   478
	inline TBufC8(const TDesC8 &aDes);
williamr@2
   479
	inline TBufC8<S> &operator=(const TUint8 *aString);
williamr@2
   480
	inline TBufC8<S> &operator=(const TDesC8 &aDes);
williamr@2
   481
	inline TPtr8 Des();
williamr@2
   482
protected:
williamr@2
   483
	TUint8 iBuf[__Align8(S)];
williamr@2
   484
	};
williamr@2
   485
//
williamr@2
   486
class TBufBase8 : public TDes8
williamr@2
   487
/**
williamr@2
   488
@internalAll
williamr@2
   489
*/
williamr@2
   490
	{
williamr@2
   491
protected:
williamr@2
   492
	IMPORT_C TBufBase8(TInt aMaxLength);
williamr@2
   493
	IMPORT_C TBufBase8(TInt aLength,TInt aMaxLength);
williamr@2
   494
	IMPORT_C TBufBase8(const TUint8* aString,TInt aMaxLength);
williamr@2
   495
	IMPORT_C TBufBase8(const TDesC8& aDes,TInt aMaxLength);
williamr@2
   496
	};
williamr@2
   497
//
williamr@2
   498
template <TInt S>
williamr@2
   499
class TBuf8 : public TBufBase8
williamr@2
   500
/**
williamr@2
   501
@publishedAll
williamr@2
   502
@released
williamr@2
   503
williamr@2
   504
A descriptor class which provides a buffer of fixed length for
williamr@2
   505
containing, accessing and manipulating TUint8 data.
williamr@2
   506
williamr@2
   507
The class is intended for instantiation. The 8-bit data that the descriptor 
williamr@2
   508
represents is part of the descriptor object itself.
williamr@2
   509
williamr@2
   510
The class is templated, based on an integer value which determines the size 
williamr@2
   511
of the data area which is created as part of the buffer descriptor object; 
williamr@2
   512
this is also the maximum length of the descriptor.
williamr@2
   513
williamr@2
   514
The data is intended to be both accessed and modified. The base classes provide 
williamr@2
   515
the functions through which the data is accessed.
williamr@2
   516
williamr@2
   517
@see TBuf
williamr@2
   518
@see TDesC8
williamr@2
   519
@see TDes8
williamr@2
   520
@see TPtr8
williamr@2
   521
*/
williamr@2
   522
	{
williamr@2
   523
public:
williamr@2
   524
	inline TBuf8();
williamr@2
   525
	inline explicit TBuf8(TInt aLength);
williamr@2
   526
    inline TBuf8(const TUint8* aString);
williamr@2
   527
	inline TBuf8(const TDesC8& aDes);
williamr@2
   528
	inline TBuf8<S>& operator=(const TUint8* aString);
williamr@2
   529
	inline TBuf8<S>& operator=(const TDesC8& aDes);
williamr@2
   530
	inline TBuf8<S>& operator=(const TBuf8<S>& aBuf);
williamr@2
   531
protected:
williamr@2
   532
	TUint8 iBuf[__Align8(S)];
williamr@2
   533
	};
williamr@2
   534
williamr@2
   535
//
williamr@2
   536
template <TInt S>
williamr@2
   537
class TAlignedBuf8 : public TBufBase8
williamr@2
   538
/**
williamr@2
   539
@internalComponent
williamr@2
   540
williamr@2
   541
A descriptor class functionally identical to TBuf8, the only
williamr@2
   542
difference from it being that TAlignedBuf8's internal buffer 
williamr@2
   543
is guaranteed to be 64-bit aligned.
williamr@2
   544
williamr@2
   545
At present this class is not intended for general use. It exists
williamr@2
   546
solely to support TPckgBuf which derives from it.
williamr@2
   547
williamr@2
   548
@see TBuf8
williamr@2
   549
@see TPckgBuf
williamr@2
   550
*/
williamr@2
   551
{
williamr@2
   552
public:
williamr@2
   553
	inline TAlignedBuf8();
williamr@2
   554
	inline explicit TAlignedBuf8(TInt aLength);
williamr@2
   555
    inline TAlignedBuf8(const TUint8* aString);
williamr@2
   556
	inline TAlignedBuf8(const TDesC8& aDes);
williamr@2
   557
	inline TAlignedBuf8<S>& operator=(const TUint8* aString);
williamr@2
   558
	inline TAlignedBuf8<S>& operator=(const TDesC8& aDes);
williamr@2
   559
	inline TAlignedBuf8<S>& operator=(const TAlignedBuf8<S>& aBuf);
williamr@2
   560
protected:
williamr@2
   561
	union {
williamr@2
   562
		double only_here_to_force_8byte_alignment;
williamr@2
   563
		TUint8 iBuf[__Align8(S)];
williamr@2
   564
	};
williamr@2
   565
};
williamr@2
   566
williamr@2
   567
#ifndef __KERNEL_MODE__
williamr@2
   568
williamr@2
   569
class RBuf8 : public TDes8
williamr@2
   570
/**
williamr@2
   571
@publishedAll
williamr@2
   572
@released
williamr@2
   573
williamr@2
   574
8 bit resizable buffer descriptor.
williamr@2
   575
williamr@2
   576
The class provides a buffer that contains, accesses and manipulates
williamr@2
   577
TUint8 data. The buffer itself is on the heap, and is managed by the class.
williamr@2
   578
williamr@2
   579
Internally, RBuf8 behaves in one of two ways:
williamr@2
   580
williamr@2
   581
- as a TPtr8 descriptor type, where the buffer just contains data
williamr@2
   582
- as a pointer to a heap descriptor, an HBufC8* type, where the buffer
williamr@2
   583
  contains both	descriptor information and the data.
williamr@2
   584
williamr@2
   585
Note that the handling of the distinction is hidden from view.
williamr@2
   586
williamr@2
   587
An RBuf8 object can allocate its own buffer. Alternatively, it can take
williamr@2
   588
ownership of a pre-existing section of allocated memory, or it can take
williamr@2
   589
ownership of a pre-existing heap descriptor. It can also reallocate the buffer
williamr@2
   590
to resize it. Regardless of the way in which the buffer has been allocated,
williamr@2
   591
the RBuf8 object is responsible for freeing memory when the object itself is closed.
williamr@2
   592
williamr@2
   593
The class is intended for instantiation.
williamr@2
   594
williamr@2
   595
The class is derived from TDes8, which means that data can be both accessed
williamr@2
   596
and modified. The base classes provide the functions through which the data is
williamr@2
   597
accessed. In addition, an RBuf8 object can be passed to any function that is
williamr@2
   598
prototyped to take a TDes8 or a TDesC8 type.
williamr@2
   599
williamr@2
   600
@see TBuf8
williamr@2
   601
@see TPtr8
williamr@2
   602
@see HBufC8
williamr@2
   603
@see TDesC8
williamr@2
   604
@see TDes8
williamr@2
   605
*/
williamr@2
   606
	{
williamr@2
   607
public:
williamr@2
   608
	IMPORT_C RBuf8();
williamr@2
   609
	IMPORT_C explicit RBuf8(HBufC8* aHBuf);
williamr@2
   610
	inline RBuf8& operator=(const TUint8* aString);
williamr@2
   611
	inline RBuf8& operator=(const TDesC8& aDes);
williamr@2
   612
	inline RBuf8& operator=(const RBuf8& aDes);
williamr@2
   613
	IMPORT_C void Assign(const RBuf8& aRBuf);
williamr@2
   614
	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength);
williamr@2
   615
	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);
williamr@2
   616
	IMPORT_C void Assign(HBufC8* aHBuf);
williamr@2
   617
	IMPORT_C void Swap(RBuf8& aRBuf);
williamr@2
   618
	IMPORT_C TInt Create(TInt aMaxLength);
williamr@2
   619
	IMPORT_C void CreateL(TInt aMaxLength);
williamr@2
   620
	IMPORT_C TInt CreateMax(TInt aMaxLength);
williamr@2
   621
	IMPORT_C void CreateMaxL(TInt aMaxLength);
williamr@2
   622
	inline void CreateL(RReadStream &aStream,TInt aMaxLength);
williamr@2
   623
	IMPORT_C TInt Create(const TDesC8& aDes);
williamr@2
   624
	IMPORT_C void CreateL(const TDesC8& aDes);
williamr@2
   625
	IMPORT_C TInt Create(const TDesC8& aDes,TInt aMaxLength);
williamr@2
   626
	IMPORT_C void CreateL(const TDesC8& aDes,TInt aMaxLength);
williamr@2
   627
	IMPORT_C TInt ReAlloc(TInt aMaxLength);
williamr@2
   628
	IMPORT_C void ReAllocL(TInt aMaxLength);
williamr@2
   629
	IMPORT_C void Close();
williamr@2
   630
	IMPORT_C void CleanupClosePushL();
williamr@2
   631
williamr@2
   632
protected:
williamr@2
   633
	IMPORT_C RBuf8(TInt aType,TInt aLength,TInt aMaxLength);
williamr@2
   634
	RBuf8(const RBuf8&); // Outlaw copy construction
williamr@2
   635
	union
williamr@2
   636
		{
williamr@2
   637
		TUint8* iEPtrType;		//Pointer to data used when RBuf is of EPtr type
williamr@2
   638
		HBufC8* iEBufCPtrType;	//Pointer to data used when RBuf is of EBufCPtr type
williamr@2
   639
		};
williamr@2
   640
	__DECLARE_TEST;
williamr@2
   641
	};
williamr@2
   642
williamr@2
   643
#endif
williamr@2
   644
williamr@2
   645
/**
williamr@2
   646
@publishedAll
williamr@2
   647
@released
williamr@2
   648
williamr@2
   649
Value reference used in operator TLitC8::__TRefDesC8()
williamr@2
   650
williamr@2
   651
@see TRefByValue
williamr@2
   652
*/
williamr@2
   653
typedef TRefByValue<const TDesC8> __TRefDesC8;
williamr@2
   654
williamr@2
   655
williamr@2
   656
williamr@2
   657
williamr@2
   658
template <TInt S>
williamr@2
   659
class TLitC8
williamr@2
   660
/**
williamr@2
   661
@publishedAll
williamr@2
   662
@released
williamr@2
   663
williamr@2
   664
Encapsulates literal text. 
williamr@2
   665
williamr@2
   666
This is always constructed using an _LIT8 macro.
williamr@2
   667
williamr@2
   668
This class is build independent; i.e. an explicit 8-bit build variant
williamr@2
   669
is generated for both a non-Unicode build and a Unicode build.
williamr@2
   670
williamr@2
   671
The class has no explicit constructors.
williamr@2
   672
williamr@2
   673
@see _LIT8
williamr@2
   674
*/
williamr@2
   675
	{
williamr@2
   676
public:
williamr@2
   677
	inline const TDesC8* operator&() const;
williamr@2
   678
	inline operator const TDesC8&() const;
williamr@2
   679
	inline const TDesC8& operator()() const;
williamr@2
   680
	inline operator const __TRefDesC8() const;
williamr@2
   681
public:
williamr@2
   682
    /**
williamr@2
   683
    @internalComponent
williamr@2
   684
    */
williamr@2
   685
	TUint iTypeLength;
williamr@2
   686
	
williamr@2
   687
	/**
williamr@2
   688
    @internalComponent
williamr@2
   689
    */
williamr@2
   690
	TText8 iBuf[__Align8(S)];
williamr@2
   691
	};
williamr@2
   692
williamr@2
   693
#endif