Programming mobile devices

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

2. Content • Descriptors • Dynamic Buffers

3. 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

4. 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...

5. Descriptors • Can be either modifiable or not • C for constant • e.g. HBufC • Either 8 or 16 bit data • e.g. TBuf8

6. Non-modifiable API • Length() • Size() • Ptr() (const TUInt *) • Alloc(), AllocL(), AllocLC() • Left(), Mid(), Right() • Find() 0 based offset or KErrNotFound • <, >, ==, !=, [] • =

7. Modifiable API • MaxLength() • MaxSize() • SetLength(),SetMax(),Zero() • Append() • Insert() • Delete() • Format() • Copy()

8. Descriptor classes • TBuf8 <n> modifiable 8 bit buffer • TBuf16 <n> modifiable 16 bit buffer • TBuf8C <n> non-modifiable 8 bit buffer • TBuf16C <n> non-modifiable 16 bit buffer • TPtr8 <n> modifiable 8 bit pointer descriptor • TPtr16 <n> modifiable 16 bit pointer descriptor

9. Descriptor classes • TPtrC8 <n> non-modifiable 8 bit pointer descriptor • TPtrC16 <n> non-modifiable 16 bit pointer descriptor • HBuf8C <n> non-modifiable 8 bit heap descriptor • HBuf16C <n> non-modifiable 16 bit heap descriptor

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

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

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

13. Buffer Descriptors • TBuf and TBufC • 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 4b • Length 28 b • Max length 32 b • Buffer

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

15. Modifying HBufC content • HBufC::Des() returns a TPtr pointer • e.g. _LIT(testString, "PLO"); HBufC *testBuf = HBufC::NewLC(testString().Length()); TPtr testPtr = testBuf->Des(); testPtr.Copy(testString);

16. HBufC::ReAlloc • Very handy for incrementing the size of a HBufC • e.g. HBufC *firstBuf = HBufC::NewLC(10); .... firstBuf=firstBuf->ReAlloc(20); ...

17. HBufC::ReAlloc • 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 ReAllocLC

18. 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

19. TBuf • _LIT(KString2," world"); • buf.Append(KString2); 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)

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

21. Descriptors as arguments • Often base class types used • TDes and TDesC • e.g. void doSomething(const &TDesC) void doMore(&TDes)

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

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

24. Search • using function Find _LIT(KStr1, "example text for searching"); _LIT(KStr2, "for"); TBuf<40> str1(KStr1); TInt result = str1.Find(KStr1); returns either -1 (KErrNotFound) or the position

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

26. Substrings • Left • Right • Mid • e.g. _LIT(KStr1, "Symbian programming..."); TBuf<10> str1(KStr1); TPtrC result = str1.Left(7); // Symbian TPtrC result = str1.Mid(12,4); // gram

27. Copying to a descriptor • use Copy() • replaces existing data • updates the size • CopyCP capital • CopyLC lower case • CopyUC upper case

28. Copying to a descriptor TUInt8 binaryData[4] = {0xB0,0xB1,0xB2,0xB3}; TBuf8<sizeof(binaryData)> binDescr; binDescr.Copy(binaryData, sizeof(binaryData));

29. Appending to a descriptor _LIT(KStr1, "PLO"); _LIT(KStr2, " course"); TBuf<20> str(KStr1); TInt result = str.Append(KStr2);