Unicode Support

IXFile supports Unicode in three topics: Unicode system calls, Unicode methods and Unicode text data. Although all have Unicode in common and are often used collectively, they concern different aspects of Unicode and therefore should not be confused. With Unicode supported, development of applications designed for international markets is simple and straightforward.

Unicode System Calls

On Windows NT, 2000 and XP Unicode is supported natively and operating system uses it exclusively for character and string manipulation to simplify localization of software and improve multilingual text processing. Windows functions with text parameters are provided in Unicode and ANSI versions to allow developers building both Unicode and ANSI applications.

IXFile internally calls Windows system functions to perform file operations. It uses either Unicode or ANSI version of system function depending on method and configuration. Following methods when called with Unicode arguments result in using Windows Unicode functions: Open, OpenAdvanced, CheckFile, CopyFile, MoveFile, DeleteFile, GetFolder, MakePath, SplitPath and GetErrorDescription. All other methods - even those with Unicode parameters - do not involve Unicode system functions. Unicode is enabled by default but can be disabled or enabled any time with EnableUnicode method. To check current status of Unicode system calls, IsUnicodeEnabled should be called.

Unicode system calls in conjunction with Unicode methods greatly simplifies developing applications for international markets. There is only one version of IXFile library which can be used for both Unicode and non-Unicode applications depending on your needs. Library exposes overloaded Unicode and ANSI methods that allows C++ developers to maintain single set of sources for both character sets.

Unicode Methods

All IXFile methods with text parameters are available in overloaded versions for ANSI and Unicode character set. Both versions can be used on Unicode and non-Unicode systems depending on your needs, because IXFile internally handles conversion to appropriate character set. Conversion between ANSI and Unicode takes place whenever text data passed to the method has different encoding then data which this method operates on. Type of text encoding is determined solely by functionality of the method but not by version of the method; if parameter passed to the method is encoded differently, it is converted to appropriate format. For example when you call ANSI method for reading Unicode text, it is always read from file as Unicode and then converted to ANSI before returning to the user. By default ANSI code page is used for conversion but SetCodePage can be called any time to change active code page. GetCodePage method should be used to retrieve identifier of the active code page.

Unicode methods in conjunction with Unicode system calls simplifies developing applications for Unicode platforms. There is only one version of IXFile library which can be used for both Unicode and non-Unicode applications. C++ developers can use TCHAR data type and set UNICODE definition to switch between ANSI and Unicode character set, thus allowing the same source to be compiled to application that supports either ANSI or Unicode character set. Visual Basic developers have only one version of IXFile methods because VB subsystem uses Unicode internally.

Although Unicode methods can be used on all systems regardless of Unicode support, some methods behave differently on Unicode and ANSI systems, as described in Unicode System Calls.

Unicode Text Data

IXFile can operate on various data types including text. Textual data can be stored in file in several formats and can have ANSI or Unicode character encoding. Unicode text is always stored as 16 bit wide characters and ANSI text as 8 bit characters. Additional data can be also stored in file depending on text format. Unicode text encoding solely determines type of character encoding and does not depend in any way on Unicode system calls or Unicode methods and can be used on all platforms regardless of actual Unicode support. There are separate methods for accessing ANSI and Unicode text: GetText, PutText, FindText and LockText operate on ANSI text; GetUnicodeText, PutUnicodeText, FindUnicodeText and LockUnicodeText operate on Unicode text. Type of text encoding is determined solely by functionality of the method but not by version (ANSI or Unicode) of the method; if parameter passed to the method is encoded differently, it is converted to appropriate format. For example, when you call ANSI method for reading Unicode text, it is always read from file as Unicode and then converted to ANSI before returning to the user. By default ANSI code page is used for conversion but SetCodePage can be called any time to change active code page.

Examples

C++

// error handling is omitted for clarity


// by setting UNICODE definition you can switch between ANSI and Unicode code generation

  #define UNICODE

  #ifdef UNICODE
   #define _UNICODE     // for _TCHAR data type
  #endif


  int _tmain(int, _TCHAR**)
  {
   IFile ixf;
   _TCHAR txt[256];

// license key can be either ANSI or Unicode

   ixf.SetLicenseKey("YOURLICENSEKEY");

// standard initialization

   ixf.Initialize(); 
  
// depending on _UNICODE definition file can be opened with Unicode or ANSI version of Open() method
// because text argument is expanded to either ANSI or Unicode string, forcing compilation of appropriate method
// in addition Unicode version of the method involves Unicode system calls on NT platforms

   ixf.Open(_T("data.txt"));

// read ANSI text
// if UNICODE is defined, retrieved data is converted to Unicode because "txt" argument is Unicode
// if UNICODE is not defined, data is returned without any convertion because "txt" argument is ANSI

   ixf.GetText(txt, sizeof(txt));

// read Unicode text
// if UNICODE is defined, data is returned without any convertion because "txt" argument is Unicode
// if UNICODE is not defined, retrieved data is converted to ANSI because "txt" argument is ANSI

   ixf.GetUnicodeText(txt, sizeof(txt));

   .
   .
   .

// write ANSI text
// if UNICODE is defined, data is converted to ANSI before writing because "txt" argument is Unicode
// if UNICODE is not defined, data is written without any conversion because "txt" argument is ANSI

   ixf.PutText(txt);

// write Unicode text
// if UNICODE is defined, data is written without any convertion because "txt" argument is Unicode
// if UNICODE is not defined, data is converted to Unicode before writing because "txt" argument is ANSI

   ixf.PutUnicodeText(txt);

   .
   .
   .

   return(0);
  }

BASIC

' error handling is omitted for clarity


' Visual Basic uses Unicode internally - all text variables and constants are Unicode


  Sub Main()

   Dim ixf As IXFile
   Dim txt As String

   Set ixf = New IXFile

' license key can be either ANSI or Unicode

   ixf.SetLicenseKey "YOURLICENSEKEY"

' standard initialization

   ixf.Initialize   

' Unicode system calls can be disabled to force IXFile to use ANSI system functions on NT platforms

   ixf.EnableUnicode False

' file opening involves ANSI system function because Unicode is disabled - regardless of Unicode argument

   ixf.Open "data.txt"

' read ANSI text
' data is converted to Unicode because "txt" argument is Unicode

   ixf.GetText txt

' read Unicode text
' data is returned without any conversion because "txt" argument is Unicode

   ixf.GetUnicodeText txt

   .
   .
   .

' write ANSI text
' data is converted to ANSI because "txt" argument is Unicode

   ixf.PutText txt

' write Unicode text
' data is written without any conversion because "txt" argument is Unicode

   ixf.PutUnicodeText txt

   .
   .
   .

  End Sub

See Also

EnableUnicode, IsUnicodeEnabled, SetCodePage, GetCodePage