diff options
Diffstat (limited to 'docs/wchar.txt')
| -rw-r--r-- | docs/wchar.txt | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/docs/wchar.txt b/docs/wchar.txt new file mode 100644 index 00000000000..6ad32cb45fc --- /dev/null +++ b/docs/wchar.txt @@ -0,0 +1,79 @@ +/** +@page wchar Wide Character/Unicode support in ACE + +Here's a first stab at some sort of documentation for the magic wchar stuff +in ACE. + +@subsection 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 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 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 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 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. + +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 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 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. + +*/
\ No newline at end of file |