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