String Utilities

 

[edit]Introduction

This article shows some Open C functions for string manipulation on Symbian.As all the core Symbian facilities like file-handling, sockets, IPC etc are descriptor based, it will be useful for to convert C strings to Descriptors and vice versa.These string utilities will be very useful for the Open C app developers, where user has to use native Symbian facilities and also the Open C APIs.

 

[edit]String Utility APIs

The following APIs should be linked against Open C’s libc library.

 

• wchar_t* tbuf16towchar( TDes& aArg );

The above Api converts the tbuf16 to a wide-character string. This API takes a TBuf16 as an argument and returns a pointer to the wide-character string. This will return a pointer, which points to the actual data stored with in the passed argument. That is, after getting the return pointer from the above API, if user modifies the data using that pointer, this will also reflect in the original TDes object, which has been sent to this API as an argument.

 

• char* tbuf8tochar( TDes8& aArg );

The above Api converts the tbuf8 to a character string.This API takes a TBuf8 [actually TDes8] and returns a pointer to the character string.This will return a pointer, which points to the actual data stored with in the passed argument. That is, after getting the return pointer from the above API, if user modifies the data using that pointer, this will also reflect in the original TDes8 object, which has been sent to this API as an argument.

 

• int tbuf16tochar( TDes& aSrc, char* aDes);

The above Api converts the tbuf16 to a character string. It is user responsibility to allocate a required size of char object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• int tbuf8towchar( TDes8& aSrc, wchar_t* aDes);

The above Api converts the tbuf8 to a wide-character string. It is user responsibility to allocate a required size of wide-char object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• void tbufC16towchar( TDesC& aSrc ,wchar_t* aDes );

The above Api converts the tbuf16 to a wide-character string. It is user responsibility to allocate a required size of wide-char object. Api may result in crash, if the destination object size is smaller than that of the source.

 

• void tbufC8tochar( TDesC8& aSrc, char* aDes );

The above Api converts the tbufC8 to a character string. It is user responsibility to allocate a required size of wide-char object. Api may result in crash, if the destination object size is smaller than that of the source.

 

• int tbufC16tochar( TDesC& aSrc, char* aDes );

The above Api converts the TBufC16 to a character string. It is user responsibility to allocate a required size of wide-char object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• int tbufC8towchar( TDesC8& aSrc, wchar_t* aDes );

The above Api converts the TBufC8 to a wide-character string. It is user responsibility to allocate a required size of wide-char object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• void wchartotbuf16( const wchar_t* aSrc, TDes16& aDes );

The above Api converts the wide-char to a TBuf16. It is user responsibility to allocate a required size of TBuf16 object. Api may the source.

 

• int chartotbuf16( const char *aSrc, TDes16& aDes );

The above Api converts the char to a TBuf16. It is user responsibility to allocate a required size of TBuf16 object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• int wchartotbuf8( const wchar_t* aSrc, TDes8& aDes );

The above Api converts the wide-char string to a TBuf8. It is user responsibility to allocate a required size of TBuf8 object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• void chartotbuf8( const char* aSrc, TDes8& aDes );

The above Api converts the character string to a TBuf8. It is user responsibility to allocate a required size of TBuf8 object. Api may result in crash, if the destination object size is smaller than that of the source.

 

• void wchartohbufc16( const wchar_t* aSrc, HBufC16& aDes );

The above Api converts the wide-char to a HBufC16. It is user responsibility to allocate a required size of HBufC16 object. Api may result in crash, if the destination object size is smaller than that of the source.

 

• int chartohbufc16( const char* aSrc, HBufC16& aDes );

The above Api converts the char to a HBufC16. It is user responsibility to allocate a required size of HBufC16 object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• int wchartohbufc8( const wchar_t* aSrc, HBufC8& aDes );

The above Api converts the wide-char to a HBufC8. It is user responsibility to allocate a required size of HBufC8 object. Api may result in crash, if the destination object size is smaller than that of the source. Api returns -1 in case of any error.

 

• void chartohbufc8( const char* aSrc, HBufC8& aDes );

The above Api converts the char to a HBufC8. It is user responsibility to allocate a required size of HBufC8 object. Api may result in crash, if the destination object size is smaller than that of the source.

 

[edit]Example based on the Open C Library for tbufC16tochar

For purpose of example all includes and prototype have been placed here to make the example complete. The full example is found in the SDK S60 examples at /Symbian/9.3/S60_3rd_FP2_Beta/S60Ex/OpenC_Ex/OpenCStringUtilitiesEx

// Example to test the library base on OpenC examples
 //Copyright (c) 2005-2007 Nokia Corporation.
 
 #ifdef __GCCE__
 //#include <staticlibinit_gcce.h>
 #endif
 
 // Constant strings
 _LIT( KSampleWideString, "Sample Wide String" );
 _LIT8( KSampleNarrowString, "Sample Narrow String" );
 
 
 #include <stdlib.h>
 #include <stdio.h>
 #include<e32base.h>
 
 // Header for the stringutils library
 #include "stringutils.h"
 
 #defineSIZE 50
 
 //Function prototype
 void testTbufC16();
 
   void testTbufC16()
 {
 // TBufC16 Conversions
 wchar_t wstr[SIZE];
 TBufC<SIZE> bufc(KSampleWideString);
 
 tbufC16towchar(bufc ,(wchar_t*)wstr);
 
 printf(" After tbufC16towchar........./n");
 wprintf(L"Result string: %ls/n", wstr);
 
 char str[SIZE];
 int retVal = tbufC16tochar(bufc ,str);
 if ( retVal == -1 )
 {
 printf("tbufC16tochar failed........../n"); 
 return;
 }
 
 printf(" After tbufC16tochar........./n");
 printf("Result string: %s/n", str);
     }
 
 int main() 
 {
 // TBufC16 Conversions
 testTbufC16();
 }