[89] | 1 | /*
|
---|
| 2 | * Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
| 3 | * contributor license agreements. See the NOTICE file distributed with
|
---|
| 4 | * this work for additional information regarding copyright ownership.
|
---|
| 5 | * The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
| 6 | * (the "License"); you may not use this file except in compliance with
|
---|
| 7 | * the License. You may obtain a copy of the License at
|
---|
| 8 | *
|
---|
| 9 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
| 10 | *
|
---|
| 11 | * Unless required by applicable law or agreed to in writing, software
|
---|
| 12 | * distributed under the License is distributed on an "AS IS" BASIS,
|
---|
| 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
| 14 | * See the License for the specific language governing permissions and
|
---|
| 15 | * limitations under the License.
|
---|
| 16 | */
|
---|
| 17 |
|
---|
| 18 | #ifndef _LOG4CXX_HELPERS_TCHAR_H
|
---|
| 19 | #define _LOG4CXX_HELPERS_TCHAR_H
|
---|
| 20 |
|
---|
| 21 | #error log4cxx/helpers/tchar.h is obsolete, see details following this line.
|
---|
| 22 |
|
---|
| 23 | /**
|
---|
| 24 | * A short history of log4cxx's tchar.h
|
---|
| 25 | *
|
---|
| 26 | * The previous log4cxx/helpers/tchar.h contained macros that
|
---|
| 27 | * attempted to replicate macros and functions defined by
|
---|
| 28 | * the Microsoft SDK's tchar.h and related header files
|
---|
| 29 | * such as _T() and TCHAR.
|
---|
| 30 | *
|
---|
| 31 | * When building apps using both log4cxx and Microsoft SDK's tchar.h,
|
---|
| 32 | * these definitions could conflict and, for example, the code generated
|
---|
| 33 | * by _T("Foo") would depend on the include order of the two
|
---|
| 34 | * tchar.h's.
|
---|
| 35 | *
|
---|
| 36 | * The motivation of tchar.h in the Microsoft SDK was to
|
---|
| 37 | * support presenting either a wide-char or multi-byte char
|
---|
| 38 | * facade to a C API depending on the presence of
|
---|
| 39 | * the _UNICODE or _MBCS preprocessor macros. When _UNICODE
|
---|
| 40 | * was set then tchar was typedef'd as wchar_t and, for example,
|
---|
| 41 | * the CreateProcess macro was defined to be CreateProcessW, If
|
---|
| 42 | * _MBCS was defined, then tchar was typedef'd as char
|
---|
| 43 | * and CreateProcess macro was defined to be CreateProcessA.
|
---|
| 44 | *
|
---|
| 45 | * In either case, the setting of _UNICODE or _MBCS
|
---|
| 46 | * didn't affect the implementation of the operating system.
|
---|
| 47 | * If you were running the Windows NT family, all the multi-byte
|
---|
| 48 | * methods delegated to a wide-char implementation.
|
---|
| 49 | * In the Windows 9x family, most wide-char methods delegated
|
---|
| 50 | * to a multi-byte implementation.
|
---|
| 51 | *
|
---|
| 52 | * In practice, most Microsoft Windows executables were either
|
---|
| 53 | * wide-char or multi-byte centric. However, they did not
|
---|
| 54 | * have to be exclusively so. An application built with
|
---|
| 55 | * _UNICODE, could still call multi-byte API functions,
|
---|
| 56 | * they would just need to explicitly call CreateProcessA
|
---|
| 57 | * instead of using the facade macro. An executable could
|
---|
| 58 | * also use both a multi-byte centric and wide-char centric
|
---|
| 59 | * DLL's since all the calls eventually hit the same
|
---|
| 60 | * underlying implementation be it a wide-char on in
|
---|
| 61 | * Windows NT or multi-char in Windows 9x.
|
---|
| 62 | *
|
---|
| 63 | * The use of log4cxx/helpers/tchar.h in log4cxx 0.9.7 was
|
---|
| 64 | * undesirable because it made log4cxx either exclusively
|
---|
| 65 | * wide-char or exclusively multi-byte and had to be consistant
|
---|
| 66 | * with the character model of the calling executable.
|
---|
| 67 | * This would make it extremely difficult to use
|
---|
| 68 | * log4cxx when DLL's with different character models
|
---|
| 69 | * where called by the same application. Since log4cxx
|
---|
| 70 | * was C++, not C, function overloading could be
|
---|
| 71 | * used instead of the CreateProcess et al macros
|
---|
| 72 | * used in the Windows headers.
|
---|
| 73 | *
|
---|
| 74 | * In the rework before the 0.9.8, the following changes
|
---|
| 75 | * were made to log4cxx:
|
---|
| 76 | *
|
---|
| 77 | * 1. All inclusions of log4cxx/helpers/tchar.h
|
---|
| 78 | * and use of TCHAR, log4cxx::String and _T
|
---|
| 79 | * were removed from log4cxx.
|
---|
| 80 | * 2. log4cxx/logstring.h was added to define the
|
---|
| 81 | * implementation character model using the log4cxx::logchar
|
---|
| 82 | * and log4cxx::LogString typedefs and LOG4CXX_STR macro.
|
---|
| 83 | * 3. Methods commonly used by calling applications were defined
|
---|
| 84 | * in both wide-char and multi-byte and both pointer and string
|
---|
| 85 | * forms with conversion to the implementation character
|
---|
| 86 | * model delayed as long as possible.
|
---|
| 87 | * 4. Use of Standard Template Library streams within
|
---|
| 88 | * log4cxx was substantially reduced (but not totally
|
---|
| 89 | * elminated).
|
---|
| 90 | * 5. The LOG4CXX_DEBUG and similar macros were simplified
|
---|
| 91 | * and now only take arguments that evaluate to
|
---|
| 92 | * character pointers or strings and no longer take
|
---|
| 93 | * the right hand side of an insertion operation:
|
---|
| 94 | *
|
---|
| 95 | * // This used to work, but no longer
|
---|
| 96 | * LOG4CXX_DEBUG(logger, "foo" << i);
|
---|
| 97 | *
|
---|
| 98 | * If you extensively used this idiom, please consider
|
---|
| 99 | * migrating to stream-like API defined in log4cxx/stream.h.
|
---|
| 100 | *
|
---|
| 101 | * 6. The LOG4CXX_DEBUG and similar use the LOG4CXX_LOCATION
|
---|
| 102 | * macro to define the log statement location instead of
|
---|
| 103 | * using __FILE__ and __LINE__. Logger::debug and
|
---|
| 104 | * similar now take const LocationInfo& instead of
|
---|
| 105 | * separate const char* and int arguments. This allows
|
---|
| 106 | * class and method names to appear in location info.
|
---|
| 107 | * 7. log4cxx include files no longer include config.h
|
---|
| 108 | * or related files. config.h and related files
|
---|
| 109 | * may be used by log4cxx implementation, but have
|
---|
| 110 | * no effect on the exposed API.
|
---|
| 111 | *
|
---|
| 112 | * It is expected that the default implementation character
|
---|
| 113 | * model will be wchar_t. However this may vary by platform
|
---|
| 114 | * and may be changed based on feedback.
|
---|
| 115 | *
|
---|
| 116 | * Developers using log4cxx should seldom be concerned
|
---|
| 117 | * with the internal character model of log4cxx unless
|
---|
| 118 | * writing custom appenders or layouts. An application
|
---|
| 119 | * should not be using log4cxx::logchar, log4cxx::LogString
|
---|
| 120 | * or LOG4CXX_STR unless dealing with something that is
|
---|
| 121 | * clearly a log4cxx internal. If you find something
|
---|
| 122 | * defined as using or returning LogString that you
|
---|
| 123 | * don't consider a log4cxx internal, please file a
|
---|
| 124 | * bug report or post a message to one of the mailing lists.
|
---|
| 125 | *
|
---|
| 126 | * wchar_t literals should be preferred in log requests since
|
---|
| 127 | * since they eliminate potential encoding confusion
|
---|
| 128 | * when the development and deployment encodings are different.
|
---|
| 129 | *
|
---|
| 130 | * Migration strategies:
|
---|
| 131 | *
|
---|
| 132 | * If you followed the examples in the previous log4cxx versions,
|
---|
| 133 | * you may have _T() macros littered through your code
|
---|
| 134 | * and inclusions of this file. If you are on the Microsoft
|
---|
| 135 | * platform, the simplest solution is to just include
|
---|
| 136 | * the Platform SDK's tchar.h which would result your log
|
---|
| 137 | * statements matching the character model of your application.
|
---|
| 138 | *
|
---|
| 139 | * If you targetting another platform and your only use of
|
---|
| 140 | * _T() in related to log4cxx, then I would recommend replacing
|
---|
| 141 | * all _T() with another macro (say MYAPP_LOGSTR())
|
---|
| 142 | * and defining that macro in a commonly included header file
|
---|
| 143 | * or defining _T() in a commonly included header file.
|
---|
| 144 | *
|
---|
| 145 | * I would first try defining these macros as
|
---|
| 146 | *
|
---|
| 147 | * #define _T(str) L ## str
|
---|
| 148 | *
|
---|
| 149 | * If that results in too many compilation errors, then try:
|
---|
| 150 | *
|
---|
| 151 | * #define _T(str) str
|
---|
| 152 | *
|
---|
| 153 | * Using the first form will result in wchar_t literals which
|
---|
| 154 | * will avoid potential encoding confusion and is expected
|
---|
| 155 | * to result in slightly better performance when logging.
|
---|
| 156 | *
|
---|
| 157 | * Since the best choice for _T() depends on the application,
|
---|
| 158 | * there is not a definition within log4cxx.
|
---|
| 159 | *
|
---|
| 160 | * Use encoding conversion macros A2T, W2T, et al should
|
---|
| 161 | * not longer be necessary. If you are doing a lot of
|
---|
| 162 | * work converting between encodings, you might consider
|
---|
| 163 | * using the stream-like interface in log4cxx/stream.h
|
---|
| 164 | * which defines insertion operators for multi-byte
|
---|
| 165 | * strings in addition to exposing all the
|
---|
| 166 | * insertion operations defined for
|
---|
| 167 | * std::basic_ostream<wchar_t>.
|
---|
| 168 | *
|
---|
| 169 | */
|
---|
| 170 |
|
---|
| 171 | #endif //_LOG4CXX_HELPERS_TCHAR_H
|
---|