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