ACE/docs/wchar.txt

   1
   2 /**
   3 @page wchar Wide Character/Unicode support in ACE
   4
   5 Here's a first stab at some sort of documentation for the magic
   6 wide-character (wchar) stuff in ACE.  It should be possible to compile
   7 ACE with wchar support on most platforms that ACE runs on.  In some
   8 cases, we don't enable wchar support by default since it increases the
   9 footprint a bit.  If you run into any problems, please use the
  10 $ACE_ROOT/PROBLEM-REPORT-FORM to let us know.
  11
  12 @subsection wchar_overview Overview
  13
  14 There are three different wchar configurations that ACE can use.  These are
  15 no support mode, regular support mode, and full support mode (well, those are
  16 the best names I can come up with for now).
  17
  18 @subsection wchar_nosupport No Support
  19
  20 By default, ACE will not use wchar_t at all.  This is for platforms where
  21 wchar_t does not exist or support for it is pretty flakey.
  22
  23 @subsection wchar_regular Regular Support
  24
  25 If ACE_HAS_WCHAR is defined, then ACE classes will be expanded to have extra
  26 methods which take in wchar_t strings.  Note that all the methods available
  27 with No Support are also available here.  This is the default in Windows
  28 right now, and has been tested to work on Linux and VxWorks (well, only been
  29 tested to compile/link of VxWorks).
  30
  31 @subsection wchar_full Full Support
  32
  33 Full support is turned on if ACE_HAS_WCHAR and ACE_USES_WCHAR are defined.
  34 Like Regular Support, both char and wchar_t versions of some methods are
  35 available, but unlike Regular Support, other methods that have char arguments
  36 or return values may have wchar_t arguments or return values.
  37
  38 This has been tested on Windows and Linux.
  39
  40 @subsection wchar_othermacros Other Important Macros
  41
  42 In addition to the ACE_HAS_WCHAR and ACE_USES_WCHAR mentioned above, there
  43 are several other macros that are important when using wide character support
  44 in ACE.
  45
  46 These other macros are used in code to conditionally switch between char and
  47 wchar_t.  ACE_TCHAR is a char normally and wchar_t when ACE_USES_WCHAR is
  48 defined.  ACE_TEXT ("foo") expands to "foo" normally and L"foo" when
  49 ACE_USES_WCHAR is defined.
  50
  51 ACE_TEXT_CHAR_TO_TCHAR and ACE_TEXT_WCHAR_TO_TCHAR are used when a string
  52 that is always a char or wchar_t string needs to be converted to a ACE_TCHAR
  53 string.  On the same note, ACE_TEXT_ALWAYS_CHAR is used when a string is
  54 ACE_TCHAR * and needs to be a char * string.
  55
  56 ACE_TEXT_WIDE ("foo") is unique in that it always maps to L"foo".  It is not
  57 a conditional macro.
  58
  59 For string constants in code, ACE_TEXT is used to put the Unicode prefix
  60 (Usually 'L') before the string when needed.  This is controlled by
  61 ACE_USES_WCHAR.
  62
  63 Finally, on Windows there are a bunch of ACE_TEXT_Apicall type macros which
  64 are used to choose the correct version of a Win32 API function depending on
  65 ACE_USES_WCHAR.  I'm hoping to remove these by adding a new ACE_OS_Win32
  66 class to perform the same task, but until then these ugly macros get the job
  67 done.
  68
  69 @subsection wchar_logmsg ACE_Log_Msg support
  70
  71 One of the more troublesome aspect of supporting wide and Ansi strings is
  72 the fact that the format strings for ACE_DEBUG and family always had to have
  73 ACE_TEXT around them.
  74
  75 Now this should not be the case, since ACE_Log_Msg was extended to support
  76 both types of format strings concurrently.  This is okay, but when strings
  77 are printed out via the format_string, care has to be taken.
  78
  79 It is interesting how Unix and Windows treats the format specifiers
  80 differently, based on their history.  Win32 uses %s, %c, %S and %C, whereas
  81 Linux seems to use %s, %c, %ls, and %lc.  And they even treat %s and %c
  82 differently.  The route ACE takes is a bit of a mixture of both:
  83
  84 - %c: prints out an Ansi character
  85 - %C: prints out an Ansi string
  86 - %s: prints out an ACE_TCHAR string
  87 - %w: prints out a Wide character
  88 - %W: prints out a Wide string
  89
  90 An example, which will also function correctly even when ACE_USES_WCHAR is
  91 defined:
  92
  93 @verbatim
  94 void print (char *a_str, wchar_t *w_str, ACE_TCHAR *t_str)
  95 {
  96     ACE_DEBUG ((LM_DEBUG,
  97                 "%C %s %W\n",
  98                 a_str,
  99                 t_str,
 100                 w_str));
 101 }
 102 @endverbatim
 103
 104 @subsection wchar_win32macros Relation to Win32's UNICODE and _UNICODE macros
 105
 106 It used to be that in previous versions of ACE that the Win32 macros affected
 107 ACE in some way.  This has been all removed in favor of the ACE_USES_WCHAR
 108 and ACE_HAS_WCHAR macros.  Along with this, the definition of some of the
 109 Win32 string types (LPTSTR, LPCSTR, etc.) have been also removed.  Since this
 110 isn't a direct concern of ACE, they will have to be defined separately if
 111 they are needed on non-Win32 platforms.
 112
 113 The way I'd recommend doing this is to add the typdefs to config.h.
 114
 115 @subsection wchar_legacy Legacy Support
 116
 117 Most of the old macros (ACE_HAS_UNICODE, ACE_HAS_MOSTLY_UNICODE_APIS) are
 118 ignored by default by ACE, since the new macros replaced them.
 119
 120 */