ChangeLogTag:Mon Nov 13 03:46:21 2000 Darrell Brunsch <brunsch@uci.edu>

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