Descriptors example code

Found in: examples\Base\BufsAndStrings\Desc\BinaryData

The files reproduced here are the main files contained in the examples directory. Some extra files may be needed to run the examples, and these will be found in the appropriate examples directory.

// BinaryData.cpp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// Examples to demonstrate how descriptors can handle
// general binary data.

#include "CommonFramework.h"

//
// Common literal text
//
_LIT(KTxtNewLine,"\n");

//
// Common format strings
//
_LIT(KCommonFormat2,"Size()=%d; MaxLength()=%d\n");
_LIT(KCommonFormat3,"0x%02x ");
_LIT(KCommonFormat4,"; Length()=%d;\n");

// do the example
LOCAL_C void doExampleL()
    {
    TInt counter;
    TInt index;
    
                // For general binary data, construct an 8 bit
                // variant descriptor. Binary data is always
                // treated as 8 bit data regardless of the
                // build.
                //
                // This example constructs a TBuf8 using the
                // default constructor.                

    TBuf8<32> buffer;

                // Look at:
                // 1. Descriptor content
                // 2. Length of descriptor
                // 3. Size of descriptor
                // 4. Maximum length of descriptor
                //
                // Length is zero. Maximum length is 32.
                // Size is zero.
    _LIT(KFormat1,"\"%S\"; Length()=%d; ");
    console->Printf(KFormat1,&buffer,buffer.Length());
    console->Printf(KCommonFormat2,buffer.Size(),buffer.MaxLength());
                
                // Set up an area in memory initialised
                // with binary data.
    TUint8 data[6] = {0x00,0x01,0x02,0xAD,0xAE,0xAF};
                
                // Put data into descriptor
    buffer.Append(&data[0],sizeof(data));

                // Append the following byte values
    buffer.Append(0xFD);
    buffer.Append(0xFE);
    buffer.Append(0xFF);

                // Length is now 9; maxlength is still 32;
                // Size is always 9 regardless of build.
    counter = buffer.Length();
    console->Printf(KTxtNewLine);
    for (index = 0; index < counter; index++)
        console->Printf(KCommonFormat3,buffer[index]);

    console->Printf(KCommonFormat4,buffer.Length()
                     );
    console->Printf(KCommonFormat2,buffer.Size(),buffer.MaxLength());                           
                // We can also mix text characters and
                // general binary data.
    buffer.Append('A');
    buffer.Append('B');
    buffer.Append(0x11);                       
    
                // Show it
    counter = buffer.Length();
    console->Printf(KTxtNewLine);
    for (index = 0; index < counter; index++)
        console->Printf(KCommonFormat3,buffer[index]);
    
    console->Printf(KCommonFormat4,buffer.Length());
    console->Printf(KCommonFormat2,buffer.Size(),buffer.MaxLength());                           
    }

// BinaryData.mmp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// using relative paths for sourcepath and user includes

// No explicit capabilities required to run this.

TARGET BinaryData.exe
TARGETTYPE exe
UID 0
VENDORID 0x70000001

SOURCEPATH .
SOURCE BinaryData.cpp

USERINCLUDE .
USERINCLUDE ..\..\..\CommonFramework
SYSTEMINCLUDE \Epoc32\include

LIBRARY euser.lib

CAPABILITY None

// BLD.INF
// Component description file
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

PRJ_MMPFILES

BinaryData.mmp

The example shows how descriptors can handle general binary data by explicitly using the 8 bit descriptor class variants TBufC8<TInt>, TBuf8<TInt>, TPtr8 etc.

Contrast this with examples where descriptors contain text. These examples almost always use the non-explicit forms TBufC<TInt>, TBuf<TInt>, TPtr etc; these are typedef'd to the 16 bit variant.

• TBuf8<TInt>: 8 bit variant modifiable buffer descriptor, derived from TDes8.

The example requires no specific capabilities in order to run - and does not demonstrate any security issues.

Found in: examples\Base\BufsAndStrings\Desc\Buffer

// Buffer.cpp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// Examples to demonstrate the basic ideas of
// buffer descriptors.

#include "CommonFramework.h"

//
// Common literal text
//
_LIT(KTxtHelloWorld,"Hello World!");
_LIT(KTxtRepText,"Replacement text");
_LIT(KTxtTBufC,"TBufC: ");
_LIT(KTxtTPtr,"TPtr: ");

//
// Common Format strings
//
_LIT(KCommonFormat2,"\"%S\"; ");
_LIT(KCommonFormat3,"Descriptor at %x; Ptr()=%x; ");
_LIT(KCommonFormat6,"\"%S\"; Ptr()=%x; Length()=%d; Size()=%d\n");
_LIT(KCommonFormat7,"\"%S\"; Ptr()=%x; Length()=%d; Size()=%d; ");
_LIT(KCommonFormat8,"\nMaxLength()=%d\n");
_LIT(KCommonFormat9,"Length()=%d; Size()=%d;\n");
_LIT(KCommonFormat10,"MaxLength()=%d\n");


LOCAL_C void doExampleL()
    {               
                // Set up an area and initialise to a
                // C style string (including the NULL).
    TText cstr[13] = {'H', 'e' ,'l' ,'l' ,'o', ' ',
                 'W', 'o','r', 'l', 'd', '!', '\0'};

                // Construct a TBufC using the NULL
                // terminated string in cstr to initialise
                // it.
    TBufC<16> bufc1(&cstr[0]);

                // Look at the address of the C string
    _LIT(KFormat1,"C string at %x; \n");
    console->Printf(KFormat1,&cstr[0]);
                                                   
                // Look at:
                // 1. Descriptor content
                // 2. Address of descriptor
                // 3. Address of descriptor data area
                // 4. Length of descriptor
                // 5. Size of descriptor
                //
                // Address of descriptor data area is
                // different from the address of cstr but
                // is offset 4 from the start of the
                // descriptor itself.
                //
                // Descriptor length is 12.
                //
                // The template parameter value defines
                // the length of the descriptor data area
                // and, therefore, governs its size
                // (depending on the build variant).
                // Size of data is 24
    console->Printf(KCommonFormat2,&bufc1);
    console->Printf(KCommonFormat3,&bufc1,bufc1.Ptr());
    _LIT(KFormat4,"Length()=%d; Size()=%d\n");
    console->Printf(KFormat4,bufc1.Length(),bufc1.Size());   
                                           
                // If the TBufC is to hold string data on
                // construction, use a _LIT macro.
    TBufC<16> bufc2(KTxtHelloWorld);

                // Cannot modify existing data but can replace
                // it entirely using assignment operator.
                // The replacement text must not have a length
                // greater than 16
    bufc2 = KTxtRepText;
    _LIT(KFormat5,"\"%S\"; Length()=%d; Size()=%d\n");
    console->Printf(KFormat5,&bufc2,bufc2.Length(),bufc2.Size());

                // Replacing text which has a length > 16
                // causes panic !!
                //
                // Remove the "//" marks on the next two lines
                // to see this happen
    //_LIT(KTxtRepTextPanic,"Text replacement causes panic");
    //bufc2 = KTxtRepTextPanic;
    
    
                // The Des() function returns a TPtr to the
                // TBufC.
                // The TBufC data can be changed through
                // the TPtr.
                // The maximum length of the TPtr is the
                // value of the TBufC template parameter,
                // i.e. 16

    bufc2 = KTxtHelloWorld;
    TPtr ptr = bufc2.Des();
    
    console->Printf(KTxtTBufC);
    console->Printf(KCommonFormat6,
                    &bufc2,
                    bufc2.Ptr(),
                    bufc2.Length(),
                    bufc2.Size()
                 );
    
    console->Printf(KTxtTPtr);
    console->Printf(KCommonFormat7,
                    &ptr,
                    ptr.Ptr(),
                    ptr.Length(),
                    ptr.Size()
                 );

    console->Printf(KCommonFormat8,ptr.MaxLength());

                // Now change the TBufC data through
                // the TPtr. This is OK provided the length
                // of the changed data does not exceed 16.
                //
                // The following change deletes the last
                // character (the "!") and appends
                // the characters " & Hi".
                //
                // Note that the length of both the TBufC
                // and the TPtr reflect the changed data.
    _LIT(KTxtAndHi," & Hi");
    ptr.Delete((ptr.Length()-1),1);
    ptr.Append(KTxtAndHi);

    console->Printf(KTxtTBufC);
    console->Printf(KCommonFormat6,
                    &bufc2,
                    bufc2.Ptr(),
                    bufc2.Length(),
                    bufc2.Size()
                 );

    console->Printf(KTxtTPtr);
    console->Printf(KCommonFormat7,
                    &ptr,
                    ptr.Ptr(),
                    ptr.Length(),
                    ptr.Size()
                 );
    console->Printf(KCommonFormat8,ptr.MaxLength());

    // * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    
    _LIT(KTxtBasicConcepts,"\n-->TBuf basic concepts");
    console->Printf(KTxtBasicConcepts);
    _LIT(KTxtPressToContinue," (press any key to continue)\n");
    console->Printf(KTxtPressToContinue);
    console->Getch();

                // Construct a TBuf using a Literal         
    TBuf<16> buf(KTxtHelloWorld);
    
                // Look at:
                // 1. Descriptor content
                // 2. Address of descriptor
                // 3. Address of descriptor data area
                // 4. Length of descriptor
                // 5. Size of descriptor
                // 6. Maximum length of descriptor
                //
                // Like a TBufC, the address of the descriptor
                // data area is offset 4 from the start of the
                // descriptor itself.
                //
                // Descriptor length is 12.
                //
                // The template parameter value defines
                // the maximum length of the descriptor.
                // and, therefore, governs its size
                // (depending on the build variant).
                // Size of data is 24
                                
    console->Printf(KCommonFormat2,&buf);
    console->Printf(KCommonFormat3,&buf,buf.Ptr());
    console->Printf(KCommonFormat9,buf.Length(),buf.Size()); 
    console->Printf(KCommonFormat10,buf.MaxLength());
                       
                // The data can be modified
    buf.Append('@');
    console->Printf(KCommonFormat2,&buf);
    console->Printf(KCommonFormat9,buf.Length(),buf.Size()); 
    console->Printf(KCommonFormat10,buf.MaxLength());

             // Length can be changed; data represented
             // by the descriptor is now "Hel"
    buf.SetLength(3);
    console->Printf(KCommonFormat2,&buf);
    console->Printf(KCommonFormat9,buf.Length(),buf.Size()); 
    console->Printf(KCommonFormat10,buf.MaxLength());

                // Length can be zeroised; no data is now
                // represented by the descriptor but
                // the maximum length is still 16
    buf.Zero();
    console->Printf(KCommonFormat2,&buf);
    console->Printf(KCommonFormat9,buf.Length(),buf.Size()); 
    console->Printf(KCommonFormat10,buf.MaxLength());
                                                    
                // The data can be replaced entirely
                // using the assignment operator.
                // The replacement text must not have a
                // length greater than 16.
    buf = KTxtRepText;
    console->Printf(KCommonFormat2,&buf);
    console->Printf(KCommonFormat9,buf.Length(),buf.Size()); 
    console->Printf(KCommonFormat10,buf.MaxLength());
    
                // Replacing text which has a length > 16
                // causes panic !!
                //
                // Remove the "//" marks on the next two lines
                // to see this happen
    //_LIT(KTxtRepTextPanic,"Text replacement causes panic");
    //buf = _L("Text replacement causes panic!");
    }

This example shows the basic idea of buffer descriptors and how they are used.

• TBuf<TInt>: modifiable buffer descriptor, derived from TDes

• TBufC<TInt>: constant buffer descriptor, derived from TDesC

• TPtr: modifiable pointer descriptor, derived from TDes

The example requires no specific capabilities in order to run - and does not demonstrate any security issues.

Found in: examples\Base\BufsAndStrings\Desc\InFunct

// InFunct.cpp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// Examples to demonstrate the usage of descriptors in function interfaces.

#include "CommonFramework.h"

//
// Literal text
//

_LIT(KDataTPtrC,"A TPtrC descriptor");
_LIT(KDataTPtr,"A TPtr descriptor");
_LIT(KDataTBufC,"A TBufC descriptor");
_LIT(KDataTBuf,"A TBuf descriptor");
_LIT(KDataHBufC,"An HBufC descriptor");

//
// Common format strings
//

_LIT(KCommonFormat2,"0x%02x ");

// A set of functions called by the example code
LOCAL_C void StringRead(const TDesC& aString);
LOCAL_C void StringWrite(TDes& aString);
LOCAL_C void BufferRead(const TDesC8& aBuffer);
LOCAL_C void BufferWrite(TDes8& aBuffer);
        
// Do the example
LOCAL_C void doExampleL()
    {               
                // We create four functions:
                // StringRead()
                // StringWrite()
                // BufferRead()
                // BufferWrite()
                // to illustrate the use of descriptors
                // in function interfaces   
    
    TText area[48];
    TPtrC ptrc;
    TPtr ptr(&area[0],48);

    TBufC<48> bufc;
    TBuf<48> buf;
    HBufC* hbufcptr;

    hbufcptr = HBufC::NewL(48);

                // Set up some data for our
                // descriptors
    ptrc.Set(KDataTPtrC); // "A TPtrC descriptor"
    ptr = KDataTPtr; // "A TPtr descriptor"
    bufc = KDataTBufC; // "A TBufC descriptor"
    buf = KDataTBuf; // "A TBuf descriptor"
    *hbufcptr = KDataHBufC; // "An HBufC descriptor"

                // We can pass a reference to all
                // descriptor types to StringRead() but the
                // function cannot change the
                // descriptor content
    StringRead(ptrc); // <-- a TPtrC
    StringRead(ptr);                     // <-- a TPtr
    StringRead(bufc);                    //  <-- a TBufC
    StringRead(buf);                     // <-- a TBuf
    StringRead(*hbufcptr);               //   <-- an HBufC
                    
                // We can only pass a reference to those
                // descriptors which are derived
                // from TDes, to StringWrite();
                // these are the modifiable
                // descriptors: TPtr and TBuf.
                //
                // The compiler will not permit a reference
                // to any other descriptor type to
                // be passed.
  //StringWrite(ptrc); <-- Illegal
    StringWrite(ptr);                    //  <-- a TPtr
  //StringWrite(bufc);                   <-- Illegal
    StringWrite(buf);                    //  <-- a TBuf
  //StringWrite(*hbufcptr);              <-- Illegal

    delete hbufcptr;
    
    _LIT(KTxtPressToContinue," (press any key to continue)\n");
    console->Printf(KTxtPressToContinue);
    console->Getch();
                
    TUint8 data1[3] = {0x00,0x01,0x02};
    TUint8 data2[3] = {0x03,0x04,0x05};
    TUint8 data3[3] = {0x06,0x07,0x08};
    TUint8 data4[3] = {0x09,0x0A,0x0B};
    TUint8 data5[3] = {0x0C,0x0D,0x0E};
                        
                // Use the 8 bit variants explicitly for
                // general binary data.

                // ptrc8's data area is data1[]
                // ptr8's data areais data2[]
    TPtrC8 ptrc8(&data1[0],3);
    TPtr8 ptr8(&data2[0],3,3);

                // bufc8 contains a copy of data3[] data
                // buf8 contains a copy of data4[] data
                // hbufcptr8 contains a copy of data5[] data
    TBufC8<3> bufc8= TPtrC8(&data3[0],3);
    TBuf8<3> buf8= TPtrC8(&data4[0],3);
    HBufC8* hbufcptr8;

    hbufcptr8 = HBufC8::NewL(3);
    *hbufcptr8 = TPtrC8(&data5[0],3);

                // We can pass a reference to all
                // descriptor types to BufferRead()
                // but the function cannot change the
                // descriptor content
    BufferRead(ptrc8); // <-- a TPtrC
    BufferRead(ptr8);                    //  <-- a TPtr
    BufferRead(bufc8);                   //   <-- a TBufC
    BufferRead(buf8);                    //  <-- a TBuf
    BufferRead(*hbufcptr8);              //    <-- an HBufC
    
                // We can only pass a reference to those
                // descriptors which are derived
                // from TDes, to BufferWrite; these are
                // the modifiable descriptors: TPtr and TBuf.
                //
                // The compiler will not permit a reference
                // to any other descriptor type to
                // be passed.
  //BufferWrite(ptrc8); <-- Illegal
    BufferWrite(ptr8);                   //   <-- a TPtr
  //BufferWrite(bufc8);                  <-- Illegal
    BufferWrite(buf8);                   //   <-- a TBuf
  //BufferWrite(*hbufcptr8);             <-- Illegal            

    delete hbufcptr8;
    }



// ************************************************
// Functions used by doInterface()
// ************************************************
LOCAL_C void StringRead(const TDesC& aString)
    {
                // A function which handles the content
                // of ANY descriptor passed to it but CANNOT
                // change that descriptor.
                //
                // Function displays descriptor content,
                // length and size.
                //
                // All descriptors can be passed to this
                // function because all descriptors are
                // ultimately derived from TDesC.
                //
                // Note, however, that all data members and
                // function members in the TDes abstract class
                // cannot be accessed (recall that TDes is
                // derived from TDesC).
                // These include the data member containing
                // the maximum length and all modifying
                // member functions.
    
    _LIT(KFormat5,"\"%S\"; %d; %d\n");
    console->Printf(KFormat5,&aString,aString.Length(),aString.Size());
    }


LOCAL_C void StringWrite(TDes& aString)
    {
                // A function which handles the content
                // of a descriptor derived from TDes;
                // i.e. the modifiable descriptors TPtr and
                // TBuf.
                //
                // Function changes the content of the
                // referenced descriptors and then displays
                // their content, length, size and maximum
                // length.
                //
                // Note that the references to TPtrC, TBufC
                // and HBufC cannot be passed.
    _LIT(KTxtModStringWrite," modified by StringWrite");          
    aString.Append(KTxtModStringWrite);
    _LIT(KFormat3,"\"%S\"; %d; %d; %d\n");
    console->Printf(KFormat3,
                    &aString,
                    aString.Length(),
                    aString.Size(),
                    aString.MaxLength()
                 );
    }


LOCAL_C void BufferRead(const TDesC8& aBuffer)
    {
                // A function which handles the content
                // of ANY descriptor passed to it but
                // CANNOT change that descriptor.
                //
                // Function displays descriptor content,
                // length and size.
                //
                // All descriptors can be passed to this
                // function because all descriptors are
                // ultimately derived from TDesC.
                //
                // Note, however, that all data members
                // and function members in the TDes abstract
                // class cannot be accessed (recall that
                // TDes is derived from TDesC).
                // These include the data member containing
                // the maximum length and all modifying
                // member functions.
    for (TInt ix = 0; ix < aBuffer.Length(); ix++)
        console->Printf(KCommonFormat2,aBuffer[ix]);
    
    _LIT(KFormat4,"; %d; %d\n");
    console->Printf(KFormat4,aBuffer.Length(),aBuffer.Size());   
    }


LOCAL_C void BufferWrite(TDes8& aBuffer)
    {
                // A function which handles the content
                // of a descriptor derived from TDes;
                // i.e. the modifiable descriptors TPtr
                // and TBuf
                //
                // Function changes the content of the
                // referenced descriptors and then displays
                // their content, length, size and maximum
                // length.
                //
                // Note that the references to TPtrC, TBufC
                // and HBufC cannot be passed.

    _LIT(KTxtModBufferWrite,"Modified by BufferWrite ");          
    console->Printf(KTxtModBufferWrite);
                
    for (TInt ix = 0; ix < aBuffer.Length(); ix++)
        {
        aBuffer[ix] += 0xF0;
        console->Printf(KCommonFormat2,aBuffer[ix]);
        }

    _LIT(KFormat1,"; %d; %d; %d\n");
    console->Printf(KFormat1,
         aBuffer.Length(),
                    aBuffer.Size(),
                    aBuffer.MaxLength()
                 );
    }

This example shows how descriptors can be used in function interfaces. Specifically, it shows the use of:

• const TDesC& aString

• TDes&

• const TDesC8& aBuffer

• TDes8& aBuffer

as function arguments.

• TBuf<TInt>: modifiable buffer descriptor, derived from TDes

• TBufC<TInt>: constant buffer descriptor, derived from TDesC

• TPtr: modifiable pointer descriptor, derived from TDes

• TPtrC: constant pointer descriptor, derived from TDesC

• HBufC: heap buffer descriptor

The example requires no specific capabilities in order to run - and does not demonstrate any security issues.

Found in: examples\Base\BufsAndStrings\Desc\HeapBuffer

// HeapBuffer.cpp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// Examples to demonstrate the basic ideas of heap buffer descriptors.

#include "CommonFramework.h"

//
// Common literal text
//
_LIT(KTxtHelloWorld,"Hello World!");
_LIT(KTxtHelloWorldMorning,"Hello World! Morning");
_LIT(KTxtAndHi," & Hi");

//
// Common Format strings
//
_LIT(KCommonFormat1,"Size()=%d;\nMaxLength()=%d\n");
_LIT(KCommonFormat2,"Ptr()=%x; Length()=%d; ");
_LIT(KCommonFormat5,"Ptr()=%x; Length()=%d; Size()=%d\n");


// Do the example
LOCAL_C void doExampleL()
    {
    
                // An HBufC is always constructed on the heap
                // using the static New(), NewL() or NewLC()
    HBufC* buf;

                // Construct an HBufC.
                // This descriptor can hold up to 15 data
                // items.
                // The current length is zero
    buf = HBufC::NewL(15);
    CleanupStack::PushL(buf);

                // Note, we could replace the above two lines of code
                // with the single line: buf = HBufC::NewLC(15);


                // Show 1. Content
                // 2. address of descriptor
                // 3. address of descriptor data area
                // 4. length of descriptor
                // 5. size of descriptor
                // The address of the descriptor data area
                // is offset 4 from the start of the
                // descriptor itself.
    _LIT(KFormat10,"\"%S\"; descriptor at %x; ");
    console->Printf(KFormat10,buf,buf);
    console->Printf(KCommonFormat5,buf->Ptr(),buf->Length(),buf->Size());
                       
                // Set up some data into the HBufC
    *buf = KTxtHelloWorld; // "Hello World!"

                // Show 1. Content
                // 2. length of descriptor
                // 3. size of descriptor
    _LIT(KFormat9,"\"%S\"; ");
    console->Printf(KFormat9,buf);
    _LIT(KFormat8,"Length()=%d; Size()=%d\n");
    console->Printf(KFormat8,buf->Length(),buf->Size());

                // Now want to replace the text with:
                // "Hello World! Morning"
                // Resulting length would be > 15
                // So, reallocate the HBufc first
                // to make it bigger

    buf = buf->ReAllocL(20);

                // Assign the new text.
    *buf = KTxtHelloWorldMorning; // "Hello World! Morning"

                // Show it
    _LIT(KFormat7,"\n\"%S\"; \n(1st realloc') desc'at %x; ");
    console->Printf(KFormat7,buf,buf);
    console->Printf(KCommonFormat5,buf->Ptr(),buf->Length(),buf->Size());           

                // buf may point to the same area as before.
                // In general, this is not the case so DO
                // NOT ASSUME.
    
    buf = buf->ReAllocL(22);
    _LIT(KFormat6,"\n\"%S\"; \n(2nd realloc') desc'at %x; ");
    console->Printf(KFormat6,buf,buf);
    console->Printf(KCommonFormat5,buf->Ptr(),buf->Length(),buf->Size());
    
                // The Des() function returns a TPtr to the
                // HBufC.
                // The HBufC data can be changed through
                // the TPtr.
                // The maximum length of the TPtr is
                // determined from the size of the cell
                // allocated to the data area of the HBufC.
                // In this example, the value has been rounded
                // up to 24.
    TPtr ptr = buf->Des();

    _LIT(KFormat11,"TPtr descriptor at %x; ");
    console->Printf(KFormat11,&ptr);
    console->Printf(KCommonFormat2,ptr.Ptr(),ptr.Length());
    console->Printf(KCommonFormat1,ptr.Size(),ptr.MaxLength());

                // Now change the HBufC data through
                // the TPtr. This is OK provided the length
                // of the changed data does not exceed the
                // maximum length.
                //
                // The following change deletes the last
                // nine characters and then appends
                // the characters " & Hi".
                //
                // Note that the length of both the HBufC
                // and the TPtr reflect the changed data.
    
    ptr.Delete((ptr.Length()-9),9);
    ptr.Append(KTxtAndHi); // " & Hi"
    
                // Look at it from HBufC's viewpoint
    _LIT(KFormat4,"\n\"%S\";\nHBufC descriptor at %x; ");
    console->Printf(KFormat4,buf,buf);

    console->Printf(KCommonFormat5,buf->Ptr(),buf->Length(),buf->Size());

                // Look at it from TPtr's viewpoint
    _LIT(KFormat3,"\"%S\"; \nTPtr descriptor at %x; ");
    console->Printf(KFormat3,&ptr,&ptr);
    console->Printf(KCommonFormat2,ptr.Ptr(),ptr.Length());
    console->Printf(KCommonFormat1,ptr.Size(),ptr.MaxLength());
                // Pop the HBufC off the cleanup stack
                // and destroy it (i.e. the HBufC)
    CleanupStack::PopAndDestroy();
    }


    
    

The example shows use of the HBufC heap buffer descriptor and:

• how it can be created using the HBufC::NewL() static function

• how it can be reallocated using the ReAllocL() function

• how its data can be changed through a TPtr constructed by calling the Des() function

• HBufC: heap buffer descriptor

• TPtr: modifiable pointer descriptor, derived from TDes

• CleanupStack: a cleanup stack

The example requires no specific capabilities in order to run - and does not demonstrate any security issues.

Found in: examples\Base\BufsAndStrings\Desc\Modifier

// Modifier.cpp
//
// Copyright (C) Symbian Software Ltd 2000-2005. All rights reserved.

// Examples to demonstrate some of the modifying member
// functions of descriptors.

#include "CommonFramework.h"

//
// Common literal text
//
_LIT(KPressAnyKeyToContinue," (press any key to continue)\n");
_LIT(KTextHelloWorld,"Hello World!");
_LIT(KTextHello,"Hello");
_LIT(KTextXYZ,"XYZ");
_LIT(KTextDinner,"D\214ner \205 la Fran\207ais");

//
// Common format strings
//

_LIT(KFormatfourex,"%4x");
_LIT(KFormatBufLenSizeMax,"\"%S\"; %d; %d; %d\n");
_LIT(KFormatLenSizeMax,"; %d; %d; %d\n");
_LIT(KFormatBufLen,"\"%S\"; Length()=%d; ");
_LIT(KFormatSizeMax,"Size()=%d; MaxLength()=%d\n");
_LIT(KFormatCommon,"0x%02x ");

            // Define and implement
            // the overflow handler used
            // by the AppendFormat() example.

class TestOverflow : public TDesOverflow
    {
    void Overflow(TDes& aDes);
    };


void TestOverflow::Overflow(TDes& aDes)
    {
    _LIT(KTextDescOverflow,"Descriptor overflow - maxlength %d\n");
    console->Printf(KTextDescOverflow,aDes.MaxLength());
    }


// Do the example
LOCAL_C void doExampleL()
    {               

    TInt index;
    TInt counter;

                // Use a TBuf to demonstrate some of these
    TBuf<32> buf(KTextHelloWorld);
        
            //              
            // Copy(),CopyF(), CopyUC() & CopyCP() * * *
            //
            // Note that CopyF() CopyUC() & CopyCP() are locale dependent

    _LIT(KTitleCopy,"\n--->Copy(),CopyF(),CopyUC() & CopyCP()\n");
    _LIT(KNoteAboutLocale1,"\nNote that the behaviour of CopyF(), CopyUC() & CopyCP() is\n");
    _LIT(KNoteAboutLocale2,"dependent on the locale.\n");
    console->Printf(KTitleCopy);
    console->Printf(KNoteAboutLocale1);
    console->Printf(KNoteAboutLocale2);
                        
                // Show buf's content,length,size and
                // maximum size.
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());

                // Copy normal
    buf.Copy(KTextDinner);

                // Show buf's content,length,size and
                // maximum size.
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
    

                // Copy folded - accents are not preserved
                //
                // (NB the display may use a different code
                // page to that used by the base, in which
                // case the accents will seem to be preserved)
    buf.CopyF(KTextDinner);
                
                // Show buf's new content,length,size
                // and max size
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
                // Copy uppercase
                // Note that accents are preserved.
    buf.CopyUC(KTextDinner);
                
                // Show buf's new content,length,size
                // and maximum size
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());

                // Copy capitalised
                // Note that accents are preserved.
    _LIT(KTextCatOnMat,"tHe CaT sAt On ThE mAt - voil\205");
    buf.CopyCP(KTextCatOnMat);
                
                // Show buf's new content,length,size
                // and max size
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
                       
                // Length of copied text > 32 causes panic !!
                //
                // Remove the "//" marks on the next two lines
                // to see this happen
    //_LIT(KTxtCausePanic1,"Panic caused by an attempt to replace text.");
    //buf.Copy(KTxtCausePanic1);
    
            //
            // Append() & operator+= * * * * * * * * *
            //
    _LIT(KTitleAppend,"\n--->Append & Operator+=");
    console->Printf(KTitleAppend);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();

                // Show buf's content,length,size and
                // maximum size.
    buf = KTextHelloWorld;
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());

                // Append:
                // 1. a single character
                // 2. a descriptor
                // 3. another descrptor using operator +=
                //
                // Generates the string
                // "Hello World!@XYZ##" in buf
    buf.Append('@');
    buf.Append(KTextXYZ);
    _LIT(KTextHashHash,"##");
    buf += KTextHashHash;
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());

            //              
            // Swap() * * * * * * * * * * * * * * *
            //
    _LIT(KTitleSwap,"\n--->Swap()");
    console->Printf(KTitleSwap);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();
    
    _LIT(KWhatANiceDay,"What a nice day");
    TBuf<16> altbuf1(KWhatANiceDay);
    buf = KTextHelloWorld;

                // Show buf and altbuf BEFORE swap
    _LIT(KTextBefore," BEFORE...\n");
    console->Printf(KTextBefore);
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
    
    console->Printf(KFormatBufLen,&altbuf1,altbuf1.Length());
    console->Printf(KFormatSizeMax,altbuf1.Size(),altbuf1.MaxLength());
    
                // now swap the descriptors and look at
                // buf and altbuf again;
                // The content, length and size of the
                // descriptors have swapped; their maximum
                // lengths have NOT changed.
    buf.Swap(altbuf1);

    _LIT(KTextAfter," AFTER...\n");
    console->Printf(KTextAfter);
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
    
    console->Printf(KFormatBufLen,&altbuf1,altbuf1.Length());
    console->Printf(KFormatSizeMax,altbuf1.Size(),altbuf1.MaxLength()
                     );

                // Swap is ok provided the maximum length
                // of each descriptor is big enough to
                // hold the other's data.
    
                // altbuf2 is too small to accommodate
                // buf's data !!
                //
                // Remove the "//" marks on the next three lines
                // to see this panic
    //_LIT(KTxtxxx,"xxx");
    //TBuf<8> altbuf2(KTxtxxx);
    //buf = KTextHelloWorld;
    //buf.Swap(altbuf2);
    
    
            //              
            // Repeat() * * * * * * * * * * * * * * *
            //
    _LIT(KTitleRepeat,"\n--->Repeat()");
    console->Printf(KTitleRepeat);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();

                // Set current length of buf to 16 and
                // copy repeat the characters "Hello".
                // The descriptor is filled up to
                // its CURRENT LENGTH.
                // Result is the 16 charcters
                // "HelloHelloHelloH"
                //
                // Note the truncation.
    buf.SetLength(16);
    buf.Repeat(KTextHello);

                // Look at it.
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());

                // Now set the length to 8 characters
                // and do Repeat again.
                // Result is the 8 characters
                // "HelloHel"

    buf.SetLength(8);
    buf.Repeat(KTextHello);

                // Look at it
    console->Printf(KFormatBufLen,&buf,buf.Length());
    console->Printf(KFormatSizeMax,buf.Size(),buf.MaxLength());
    
            //               
            // Insert() & Delete() * * * * * * * * *
            //
    _LIT(KTitleInsert,"\n--->Insert() & Delete()");
    console->Printf(KTitleInsert);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();

                // set buf to contain the text "abc" and
                // look at it
    _LIT(KTextAbc,"abc");
    buf = KTextAbc;
    console->Printf(KFormatBufLenSizeMax,
                    &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // Insert the descriptor at the beginning
                // of buf to give "XYZabc"
                //
    
    buf.Insert(0,KTextXYZ);

                // Look at it
    console->Printf(KFormatBufLenSizeMax,
                    &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // Now insert another descriptor at pos 2
                // to give "XijklmnYZabc"
                //
    _LIT(KTextijklmn,"ijklmn");
    buf.Insert(1,KTextijklmn);

                // Show result
    console->Printf(KFormatBufLenSizeMax,
                    &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
                                   
    
                // Insertion point out of range
                // (> current length of descriptor)
                //
                // Remove the "//" marks on the next line
                // to see this panic
    //_LIT(KTxtqwerty,"qwerty");
    //buf.Insert(buf.Length()+1,KTxtqwerty);
    
    
                // Resulting length of data
                // is > maximum length.
                //
                // Remove the "//" marks on the next line
                // to see this panic
    //_LIT(KTxtatoz,"abcdefghijklmnopqrstuvwxyz");
    //buf.Insert(12,KTxtatoz);
    
    
                // Now delete the 3 data
                // items (characters) at the start
                // of buf to give "klmnYZabc"
    buf.Delete(0,3);

                // Show result
    console->Printf(KFormatBufLenSizeMax,
                    &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // Now delete the 4 data items (characters) at
                // position 4 to give "klmnc"
                //
    buf.Delete(4,4);
    
                // Show result
    console->Printf(KFormatBufLenSizeMax,
                    &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // An excessive length for deletion is
                // truncated to a sensible value. Deletes
                // all the data starting at pos 1 to
                // give "k"
                // (Note that the length actually
                // deleted is 4 NOT 25000).
                            
    buf.Delete(1,25000);
    
                // Show result
    console->Printf(KFormatBufLenSizeMax,
                 &buf,
                 buf.Length(),
                 buf.Size(),
                 buf.MaxLength()
                 );
        
            //              
            // TrimLeft() & TrimRight() * * * * * * * * *
            //
    _LIT(KTitleTrimLeft,"\n--->TrimLeft() & TrimRight()");
    console->Printf(KTitleTrimLeft);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();

                // set buf up and show the detail
    buf.Fill(' ',18);
    buf.Replace(3,(&KTextHelloWorld)->Length(),KTextHelloWorld);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // Remove left hand spaces  
    buf.TrimLeft(); 
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // Remove right hand spaces     
    buf.TrimRight();    
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // Trim() removes both left and right
                // hand spaces

        
            //               
            // FillZ() & Fill() * * * * * * * * * *
            //
    _LIT(KTitleFill,"\n--->FillZ() & Fill()");
    console->Printf(KTitleFill);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();
            
                // Set current length of buf
                // Fillz() fills buf up to its current length
                // with 0x00.
    buf.SetLength(8);
    buf.FillZ();

                // Show it
    counter = buf.Length();
    for (index = 0; index < counter; index++)
        console->Printf(KFormatCommon,buf[index]);
        
    console->Printf(KFormatLenSizeMax,
         buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // Fills buf up to its current length
                // with 'A'
    buf.Fill('A');
    
                // show it
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
            //              
            // Num(), NumUC(), AppendNum() & AppendNumUC()
            //
    _LIT(KTitleNum,"\n--->Num(), NumUC(), AppendNum()");
    console->Printf(KTitleNum);
    console->Printf(KPressAnyKeyToContinue);
    console->Getch();

                // convert a signed integer to
                // decimal characters
    buf.Num(-176);

                // show it
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // convert another signed integer
    buf.Num(12345);

                // show it
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                 buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );

                // convert an unsigned integer
    TUint nosign = 176;
    
                // ... into decimal characters (the default,
                // if not explicitly specified)
    buf.Num(nosign);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                 buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
                    
                // ... into binary characters
    buf.Num(nosign,EBinary);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // ... into octal characters
    buf.Num(nosign,EOctal);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // ... into lower case hex characters
    buf.Num(nosign,EHex);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );               
    
                // ... into upper case hex characters
    buf.NumUC(nosign,EHex);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                 buf.Length(),
                 buf.Size(),
                 buf.MaxLength()
                 );
            
                // Append functions the same, except
                // they append the converted data.
                // Put "xyz" into the descriptor, convert
                // and concatenate the variations.

    _LIT(KTextxyz,"xyz");             
    buf = KTextxyz;

    buf.AppendNum(nosign);
    buf.AppendNum(nosign,EBinary);
    buf.AppendNum(nosign,EOctal);
    buf.AppendNum(nosign,EHex);
    buf.AppendNumUC(nosign,EHex);
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
                       
            //              
            // Justify() & AppendJustify()* * *
            //
    _LIT(KTitleJustify,"\n--->Justify() & AppendJustify()");
    console->Printf(KTitleJustify);
    console->Printf(KPressAnyKeyToContinue);
    
    console->Getch();

                // source descriptor for this example has
                // length 12.
    TBufC<40> src(KTextHelloWorld);
                
                // target field in buf has width 16 (NB this
                // is greater than the length of the descriptor
                // src).
                // src is copied into target field, aligned left
                // and padded with '@' characters.
                //
                // length of buf becomes the same as the
                // specified width, i.e 16
    buf.Justify(src,16,ELeft,'@');
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // target field in buf has width 16 (NB this
                // is greater than the length of the descriptor
                // src).
                // src is copied into target field, aligned centre
                // and padded with '@' characters
                //
                // length of buf becomes the same as the
                // specified width, i.e 16
    buf.Justify(src,16,ECenter,'@');
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
                // target field in buf has width 10 (NB this
                // is smaller than the length of the descriptor
                // src).
                // src is copied into target field but truncated
                // to 10 characters and, therefore, alignment and
                // padding information not used.
                //
                // length of buf becomes the same as the
                // width, i.e 10
    buf.Justify(src,10,ECenter,'@');
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
        
                // target field in buf is set to the length of
                // the descriptor src (whatever it currently is)
                //
                // src copied into target field. No padding and
                // no truncatiuon needed and so the
                // alignment and padding information is not used.
                //
                // length of buf becomes the same as the length
                // of src i.e 12
    buf.Justify(src,KDefaultJustifyWidth,ECenter,'@');
    console->Printf(KFormatBufLenSizeMax,
     &buf,
                    buf.Length(),
                    buf.Size(),
                    buf.MaxLength()
                 );
    
    
    
                // implied width > maximum length of buf.
                //
                // Remove the "//" marks on the next two lines
                // to see this panic
    //_LIT(KTxtPanicCausingText,"Panic causing text because length > 32");
    //src = KTxtPanicCausingText;
    //buf.Justify(src,KDefaultJustifyWidth,ECenter,'@' );
    

    
                // explicit width > maximum length of buf
                //
                // Remove the "//" marks on the next line
                // to see this panic
    //buf.Justify(src,33,ECenter,'@');
    

                // AppendJustify() is similar but target
                // field appended to descriptor.
                //
                // Target field in buf has width 16
                // (NB greater than length of descriptor
                // src) and is appended to existing content
                // of buf.
                // src copied into target field,
                // aligned left and padded with '@'
                // characters
                //
                // Resulting length of buf is the length
                // of "ABCD" plus the width of the target
                // field (16) giving a value of 20.
    _LIT(KTextABCD,"ABCD");
  &nbs