Programming mobile devices Part II Programming Symbian devices

Programming mobile devices Part II Programming Symbian devices with Symbian C++ Strings, Buffers and data collections

Content • Descriptors • Dynamic Buffers

Descriptors • • Data buffer Buffers size Different descriptors for different purposes Methods for – writing the buffer – reading the buffer – accessing different properties of the buffer, like the size

Descriptors • Buffer – the buffer is inside the descriptor – TBuf. . . • Pointer – the buffer is outside and the descriptor contains a pointer to the buffer – TPtr. . . • Heap – HBuf. . .

Descriptors • • • Can be either modifiable or not C for constant e. g. HBuf. C Either 8 or 16 bit data e. g. TBuf 8

Non-modifiable API • • Length() Size() Ptr() (const TUInt *) Alloc(), Alloc. LC() Left(), Mid(), Right() Find() 0 based offset or KErr. Not. Found <, >, ==, !=, [] =

Modifiable API • • Max. Length() Max. Size() Set. Length(), Set. Max(), Zero() Append() Insert() Delete() Format() Copy()

Descriptor classes • • • TBuf 8 <n> modifiable 8 bit buffer TBuf 16 <n> modifiable 16 bit buffer TBuf 8 C <n> non-modifiable 8 bit buffer TBuf 16 C <n> non-modifiable 16 bit buffer TPtr 8 <n> modifiable 8 bit pointer descriptor • TPtr 16 <n> modifiable 16 bit pointer descriptor

Descriptor classes • TPtr. C 8 <n> non-modifiable 8 bit pointer descriptor • TPtr. C 16 <n> non-modifiable 16 bit pointer descriptor • HBuf 8 C <n> non-modifiable 8 bit heap descriptor • HBuf 16 C <n> non-modifiable 16 bit heap descriptor

String descriptors • 16 bit descriptors (unicode) • For binary data 8 bit descriptors • For strings we use literals, which behave like descriptors

Literals • • • _LIT _L e. g. _LIT(my. String, "Test data. . . ") behaves like a non-modifiable descriptor _LIT creates an instance of TLit. C class Can be converted to Descriptors

Literal to Descriptor • Three ways – implicit –& – () • e. g. _LIT(KMy. Example. Literal, "Test data. . . ") const TDesc *ptr = &KMy. Example. Literal; or KMy. Example. Literal(). Length();

Buffer Descriptors • TBuf and TBuf. C – the class contains the data buffer • TBuf <10> Buf would be a 16 bit descriptor with a buffer large enough for 10 16 -bit values • Type 4 b • Length 28 b • Max length 32 b • Buffer

HBuf. C • H for Heap (allocate on the heap, but does not inherit CBase) • New() if no leaving needed • New. L() if leaving necessary • New. LC() if cleanup stack needed • Alloc() can be used to create a HBuf. C from an existing descriptor

Modifying HBuf. C content • HBuf. C: : Des() returns a TPtr pointer • e. g. _LIT(test. String, "PLO"); HBuf. C *test. Buf = HBuf. C: : New. LC(test. String(). Length()); TPtr test. Ptr = test. Buf->Des(); test. Ptr. Copy(test. String);

HBuf. C: : Re. Alloc • Very handy for incrementing the size of a HBuf. C • e. g. HBuf. C *first. Buf = HBuf. C: : New. LC(10); . . first. Buf=first. Buf->Re. Alloc(20); . . .

HBuf. C: : Re. Alloc • be careful with cleanup stack (if you use cleanup stack, be sure to pop the old pointer and push the new one) • You can also use Re. Alloc. LC

TBuf • TBuf <10> buf creates an empty buffer • _LIT(KString, "Hello"); • TBuf <10> buf(KString); creates the buffer with letters Hello in it • _LIT(KString, "Hello"); • TBuf <12> buf(); • buf. Copy(KString); copies Hello into buf

TBuf • _LIT(KString 2, " world"); • buf. Append(KString 2); appends world into buf • Be careful not to go past the limit of the buffer (a buffer with 10 elements in the previous example would not be enough)

TBuf. C • • • C for constant not modifiable hence, only one length value you cannot add data you can replace old data replacing is done with = operator

Descriptors as arguments • Often base class types used • TDes and TDes. C • e. g. void do. Something(const &TDes. C) void do. More(&TDes)

. . . and return types • A function can also return a descriptor • e. g. const TDesc& my. Func() { return. . . ; }

Comparison • Strings can be compared with the Compare method, for example: _LIT(KStr 1, "PLO"); _LIT(KStr 2, "plo"); TBuf<10> str 1(KStr 1); TInt result = str 1. Compare(KStr 1); 0 for same, negative if KStr 1 is less and positive if KStr 1 is greater than str 1

Search • using function Find _LIT(KStr 1, "example text for searching"); _LIT(KStr 2, "for"); TBuf<40> str 1(KStr 1); TInt result = str 1. Find(KStr 1); returns either -1 (KErr. Not. Found) or the position

Match • Like Find, but wildcards, like * are accepted. • * any string sequence • ? any one character _LIT(KStr 1, "PLO"); _LIT(KStr 2, "? LO"); TBuf<10> str 2(KStr 2); TInt result = str 2. Match(KStr 1);

Substrings • Left • Right • Mid • e. g. _LIT(KStr 1, "Symbian programming. . . "); TBuf<10> str 1(KStr 1); TPtr. C result = str 1. Left(7); // Symbian TPtr. C result = str 1. Mid(12, 4); // gram

Copying to a descriptor • use Copy() – replaces existing data – updates the size • Copy. CP capital • Copy. LC lower case • Copy. UC upper case

Copying to a descriptor TUInt 8 binary. Data[4] = {0 x. B 0, 0 x. B 1, 0 x. B 2, 0 x. B 3}; TBuf 8<sizeof(binary. Data)> bin. Descr; bin. Descr. Copy(binary. Data, sizeof(binary. Data));

Appending to a descriptor _LIT(KStr 1, "PLO"); _LIT(KStr 2, " course"); TBuf<20> str(KStr 1); TInt result = str. Append(KStr 2);