Nokia N97 SDK Example Applications Guide |
String Utilities Library Example
1. About this Example
2. Prerequisites
3. Design and Implementation
For those who have worked on Symbian, string manipulation on Symbian is bit tricky. Even though Symbian has rich set of Apis
for formatting/manipulating strings with both UNICODE (16 bit variants) and narrow character sets (8-bits), using those Apis
will be bit complex for those who have familiarized Standard C string manipulations.
When one writes hybrid applications on Symbian using native Symbian Apis as well as Open C Apis, user may need to convert
the SYMBIAN descriptors to standard C character strings and vice versa. Especially, in case of writing hybrid applications
on open C, user will be facing this conversion problem more frequently. It is really difficult to do these conversions without
the thorough knowledge of SYMBIAN descriptors.
OpenCStringUtilitiesEx is a library, which makes Open C’s developers life easy. OpenCStringUtilitiesEx is a library, which
exports several string- utility Apis for descriptor to character string conversions and vice versa. With the help of this
library, user will be able to write a hybrid application on Open C, with out knowing much about SYMBIAN descriptors.
- tbuf16towchar
- tbuf16tochar
- tbuf8towchar
- tbufC16towchar
- tbufC8tochar
- tbufC16tochar
- tbufC8towchar
- wchartotbuf16
- chartotbuf16
- wchartotbuf8
- chartotbuf8
- wchartohbufc16
- chartohbufc16
- wchartohbufc8
- chartohbufc8
- hbufC16towchar
- hbufC16tochar
- hbufC8towchar
- hbufC8tochar
The OpenCStringUtilitiesEx Library application consists of two modules, which should be built in the following order:
- Library - which builds the generic OpenCStringUtilitiesEx library [ i.e. OpenCStringUtilitiesLibEx ].
- exe - which builds an EXE that demonstrates the usage of this library. [ i.e. OpenCStringUtilitiesExeEx ].
The definition for the whole application can be found in the bld.inf file in the group subdirectory of the applications main
directory.
This example requires a familiarity with the C programming language, and access to the OE standard library documentation.
As, this example uses OE Standard library, the reader is recommended to read the following topics from the OE SDK documentation
before proceeding:
- Standard library how to
- Descriptions on SYMBIAN descriptors is optional.
The program capabilities are defined in:
stringutils.mmp file (DLL - library): CAPABILITY NONE stringutils_example.mmp file (EXE - application): CAPABILITY NONE.
This application has 2 modules as below:
- String-utils Library( i.e. OpenCStringUtilitiesLibEx.dll) that exports set of Apis for the user(OpenCStringUtilitiesLibEx).
- An application (EXE) that demonstrates the usage of Open C Apis and also those Apis exported by String Utils Library. (OpenCStringUtilitiesLibEx)
This example will create a DLL which exports set of generic Apis for the user using which one can do SYMBIAN descriptor to
character string conversions and vice versa.
To give an rough idea on how to use these Apis, an EXE is provided that calls the Apis of OpenCStringUtilitiesLibEx and illustrates
the use of the Apis.
This DLL (OpenCMessageQueueLibraryEx) exports the following Apis:
- int tbuf16tochar( TDes& aSrc, char* aDes); This 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); This 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 ); This 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 ); This 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 ); This 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 ); This 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.
- int chartotbuf16( const char *aSrc, TDes16& aDes ); This 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 ); This 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 ); This 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 ); This 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 ); This 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 ); This 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 ); This 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.
Apart from these, it supports following Apis, which are aliased with its corresponding TBufC counterparts as shown below,
- hbufC16towchar ===> tbufC16towchar
- hbufC16tochar ===> tbufC16tochar
- hbufC8towchar ===> tbufC8towchar
- hbufC8tochar ===> tbufC8tochar [Read ===> as "an alias to"]
Internally, these api use wide character Apis of libc like:
OpenCStringUtilitiesExeEx is C Application that uses String-utils library. This application uses main() as an entry point
for the application. The application is simple console based application. This has use cases for using String-utils library
(OpenCStringUtilitiesLibEx.dll) Apis.
It has its own icon and can be launched from the UI both in the emulator and in the device.
|
© Nokia 2009
|

|