src/main/include/log4cxx/helpers/tchar.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _LOG4CXX_HELPERS_TCHAR_H
#define _LOG4CXX_HELPERS_TCHAR_H

#error log4cxx/helpers/tchar.h is obsolete, see details following this line.

/**
* A short history of log4cxx's tchar.h
*
* The previous log4cxx/helpers/tchar.h contained macros that
* attempted to replicate macros and functions defined by
* the Microsoft SDK's tchar.h and related header files
* such as _T() and TCHAR.
*
* When building apps using both log4cxx and Microsoft SDK's tchar.h,
* these definitions could conflict and, for example, the code generated
* by _T("Foo") would depend on the include order of the two
* tchar.h's.
*
* The motivation of tchar.h in the Microsoft SDK was to
* support presenting either a wide-char or multi-byte char
* facade to a C API depending on the presence of
* the _UNICODE or _MBCS preprocessor macros.  When _UNICODE
* was set then tchar was typedef'd as wchar_t and, for example,
* the CreateProcess macro was defined to be CreateProcessW,  If
* _MBCS was defined, then tchar was typedef'd as char
* and CreateProcess macro was defined to be CreateProcessA.
*
* In either case, the setting of _UNICODE or _MBCS
* didn't affect the implementation of the operating system.
* If you were running the Windows NT family, all the multi-byte
* methods delegated to a wide-char implementation.
* In the Windows 9x family, most wide-char methods delegated
* to a multi-byte implementation.
*
* In practice, most Microsoft Windows executables were either
* wide-char or multi-byte centric.  However, they did not
* have to be exclusively so.  An application built with
* _UNICODE, could still call multi-byte API functions,
* they would just need to explicitly call CreateProcessA
* instead of using the facade macro.  An executable could
* also use both a multi-byte centric and wide-char centric
* DLL's since all the calls eventually hit the same
* underlying implementation be it a wide-char on in
* Windows NT or multi-char in Windows 9x.
*
* The use of log4cxx/helpers/tchar.h in log4cxx 0.9.7 was
* undesirable because it made log4cxx either exclusively
* wide-char or exclusively multi-byte and had to be consistant
* with the character model of the calling executable.
* This would make it extremely difficult to use
* log4cxx when DLL's with different character models
* where called by the same application.  Since log4cxx
* was C++, not C, function overloading could be
* used instead of the CreateProcess et al macros
* used in the Windows headers.
*
* In the rework before the 0.9.8, the following changes
* were made to log4cxx:
*
* 1. All inclusions of log4cxx/helpers/tchar.h
*       and use of TCHAR, log4cxx::String and _T
*       were removed from log4cxx.
* 2. log4cxx/logstring.h was added to define the
*     implementation character model using the log4cxx::logchar
*     and log4cxx::LogString typedefs and LOG4CXX_STR macro.
* 3. Methods commonly used by calling applications were defined
*    in both wide-char and multi-byte and both pointer and string
*    forms with conversion to the implementation character
*    model delayed as long as possible.
* 4. Use of Standard Template Library streams within
*    log4cxx was substantially reduced (but not totally
*    elminated).
* 5. The LOG4CXX_DEBUG and similar macros were simplified
*    and now only take arguments that evaluate to
*    character pointers or strings and no longer take
*    the right hand side of an insertion operation:
*
*    //   This used to work, but no longer
*    LOG4CXX_DEBUG(logger, "foo" << i);
*
*    If you extensively used this idiom, please consider
*    migrating to stream-like API defined in log4cxx/stream.h.
*
* 6. The LOG4CXX_DEBUG and similar use the LOG4CXX_LOCATION
*    macro to define the log statement location instead of
*    using __FILE__ and __LINE__.  Logger::debug and
*    similar now take const LocationInfo& instead of
*    separate const char* and int arguments.  This allows
*    class and method names to appear in location info.
* 7. log4cxx include files no longer include config.h
*    or related files.  config.h and related files
*    may be used by log4cxx implementation, but have
*    no effect on the exposed API.
*
* It is expected that the default implementation character
* model will be wchar_t.  However this may vary by platform
* and may be changed based on feedback.
*
* Developers using log4cxx should seldom be concerned
* with the internal character model of log4cxx unless
* writing custom appenders or layouts.  An application
* should not be using log4cxx::logchar, log4cxx::LogString
* or LOG4CXX_STR unless dealing with something that is
* clearly a log4cxx internal.  If you find something
* defined as using or returning LogString that you
* don't consider a log4cxx internal, please file a
* bug report or post a message to one of the mailing lists.
*
* wchar_t literals should be preferred in log requests since
* since they eliminate potential encoding confusion
* when the development and deployment encodings are different.
*
* Migration strategies:
*
* If you followed the examples in the previous log4cxx versions,
* you may have _T() macros littered through your code
* and inclusions of this file.  If you are on the Microsoft
* platform, the simplest solution is to just include
* the Platform SDK's tchar.h which would result your log
* statements matching the character model of your application.
*
* If you targetting another platform and your only use of
* _T() in related to log4cxx, then I would recommend replacing
*  all _T() with another macro (say MYAPP_LOGSTR())
* and defining that macro in a commonly included header file
* or defining _T() in a commonly included header file.
*
* I would first try defining these macros as
*
* #define _T(str) L ## str
*
* If that results in too many compilation errors, then try:
*
* #define _T(str) str
*
* Using the first form will result in wchar_t literals which
* will avoid potential encoding confusion and is expected
* to result in slightly better performance when logging.
*
*  Since the best choice for _T() depends on the application,
*  there is not a definition within log4cxx.
*
* Use encoding conversion macros A2T, W2T, et al should
* not longer be necessary.  If you are doing a lot of
* work converting between encodings, you might consider
* using the stream-like interface in log4cxx/stream.h
* which defines insertion operators for multi-byte
* strings in addition to exposing all the
* insertion operations defined for
* std::basic_ostream<wchar_t>.
*
*/

#endif //_LOG4CXX_HELPERS_TCHAR_H