00001 /* 
00002  * File:        comstl.h
00003  *
00004  * Purpose:     Root header for the COMSTL libraries. Performs various compiler
00005  *              and platform discriminations, and definitions of types.
00006  *
00007  * Created:     15th January 2002
00008  * Updated:     11th September 2004
00009  *
00010  * Home:        http://stlsoft.org/
00011  *
00012  * Copyright (c) 2002-2004, Matthew Wilson and Synesis Software
00013  * All rights reserved.
00014  *
00015  * Redistribution and use in source and binary forms, with or without
00016  * modification, are permitted provided that the following conditions are met:
00017  *
00018  * - Redistributions of source code must retain the above copyright notice, this
00019  *   list of conditions and the following disclaimer.
00020  * - Redistributions in binary form must reproduce the above copyright notice,
00021  *   this list of conditions and the following disclaimer in the documentation
00022  *   and/or other materials provided with the distribution.
00023  * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
00024  *   any contributors may be used to endorse or promote products derived from
00025  *   this software without specific prior written permission.
00026  *
00027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00037  * POSSIBILITY OF SUCH DAMAGE.
00038  *
00039  * 
00040 
00041 
00042 #ifndef COMSTL_INCL_H_COMSTL
00043 #define COMSTL_INCL_H_COMSTL
00044 
00045 /* File version */
00046 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00047 # define COMSTL_VER_H_COMSTL_MAJOR      2
00048 # define COMSTL_VER_H_COMSTL_MINOR      0
00049 # define COMSTL_VER_H_COMSTL_REVISION   1
00050 # define COMSTL_VER_H_COMSTL_EDIT       62
00051 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00052 
00101 /* 
00102  * COMSTL version
00103  *
00104  * The libraries version information is comprised of major, minor and revision
00105  * components.
00106  *
00107  * The major version is denoted by the _COMSTL_VER_MAJOR preprocessor symbol.
00108  * A changes to the major version component implies that a dramatic change has
00109  * occurred in the libraries, such that considerable changes to source dependent
00110  * on previous versions would need to be effected.
00111  *
00112  * The minor version is denoted by the _COMSTL_VER_MINOR preprocessor symbol.
00113  * Changes to the minor version component imply that a significant change has
00114  * occurred to the libraries, either in the addition of new functionality or in
00115  * the destructive change to one or more components such that recomplilation and
00116  * code change may be necessitated.
00117  *
00118  * The revision version is denoted by the _COMSTL_VER_REVISIO preprocessor
00119  * symbol. Changes to the revision version component imply that a bug has been
00120  * fixed. Dependent code should be recompiled in order to pick up the changes.
00121  *
00122  * In addition to the individual version symbols - _COMSTL_VER_MAJOR,
00123  * _COMSTL_VER_MINOR and _COMSTL_VER_REVISION - a composite symbol _COMSTL_VER
00124  * is defined, where the upper 8 bits are 0, bits 16-23 represent the major
00125  * component,  bits 8-15 represent the minor component, and bits 0-7 represent
00126  * the revision component.
00127  *
00128  * Each release of the libraries will bear a different version, and that version
00129  * will also have its own symbol: Version 1.0.1 specifies _COMSTL_VER_1_0_1.
00130  *
00131  * Thus the symbol _COMSTL_VER may be compared meaningfully with a specific
00132  * version symbol, e.g. #if _COMSTL_VER >= _COMSTL_VER_1_0_1
00133  */
00134 
00137 
00140 
00143 
00146 
00147 #define _COMSTL_VER_MAJOR       1
00148 #define _COMSTL_VER_MINOR       4
00149 #define _COMSTL_VER_REVISION    1
00150 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00151 # define _COMSTL_VER_1_0_1      0x00010001  
00152 # define _COMSTL_VER_1_1_1      0x00010101  
00153 # define _COMSTL_VER_1_2_1      0x00010201  
00154 # define _COMSTL_VER_1_2_2      0x00010202  
00155 # define _COMSTL_VER_1_2_3      0x00010203  
00156 # define _COMSTL_VER_1_2_4      0x00010204  
00157 # define _COMSTL_VER_1_2_5      0x00010205  
00158 # define _COMSTL_VER_1_3_1      0x00010301  
00159 # define _COMSTL_VER_1_4_1      0x00010401  
00160 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00161 
00162 #define _COMSTL_VER             _COMSTL_VER_1_4_1
00163 
00164 /* 
00165  * Includes
00166  */
00167 
00168 #ifndef STLSOFT_INCL_H_STLSOFT
00169 # include "stlsoft.h"   // STLSoft root header
00170 #endif /* !STLSOFT_INCL_H_STLSOFT */
00171 #include <objbase.h>    // COM types
00172 
00173 /* 
00174  * STLSoft version compatibility
00175  */
00176 
00177 #if !defined(_STLSOFT_VER_1_5_1) || \
00178     _STLSOFT_VER < _STLSOFT_VER_1_5_1
00179 # error This version of the COMSTL libraries requires STLSoft version 1.5.1 or later
00180 #endif /* _STLSOFT_VER < _STLSOFT_VER_1_5_1 */
00181 
00182 /* 
00183  * Sanity checks
00184  *
00185  * MBCS     -   none of the libraries' code is written to support MBCS
00186  */
00187 
00188 /* Should not be MBCS. */
00189 #ifdef _MBCS
00190 # ifdef _COMSTL_STRICT
00191 #  error The COMSTL libraries are not compatible with variable length character representation schemes such as MBCS
00192 # else
00193 #  pragma message("The COMSTL libraries are not compatible with variable length character representation schemes such as MBCS")
00194 # endif /* _COMSTL_STRICT */
00195 #endif /* _MBCS */
00196 
00197 /* 
00198  * Compiler compatibility
00199  *
00200  * Currently the only compilers supported by the COMSTL libraries are
00201  *
00202  * Borland C++ 5.5, 5.51, 5.6
00203  * Digital Mars C/C++ 8.26 - 8.32
00204  * Metrowerks 2.4 & 3.0 (CodeWarrior 7.0 & 8.0)
00205  * Intel C/C++ 6.0
00206  * Visual C++ 4.2, 5.0, 6.0, 7.0
00207  */
00208 
00209 #if defined(__STLSOFT_COMPILER_IS_BORLAND)
00210 /* Borland C++ */
00211 # if __BORLANDC__ < 0x0550
00212 #  error Versions of Borland C++ prior to 5.5 are not supported by the COMSTL libraries
00213 # endif /* __BORLANDC__ */
00214 
00215 #elif defined(__STLSOFT_COMPILER_IS_COMO)
00216 /* Comeau C++ */
00217 
00218 #elif defined(__STLSOFT_COMPILER_IS_DMC)
00219 /* Digital Mars C/C++ */
00220 # if __DMC__ < 0x0826
00221 #  error Versions of Digital Mars C/C++ prior to 8.26 are not supported by the COMSTL libraries
00222 # endif /* __DMC__ */
00223 
00224 #elif defined(__STLSOFT_COMPILER_IS_GCC)
00225 /* Digital Mars C/C++ */
00226 # if __GNUC__ < 3
00227 #  error Versions of GNU C/C++ prior to 3 are not supported by the COMSTL libraries
00228 # endif /* __DMC__ */
00229 
00230 #elif defined(__STLSOFT_COMPILER_IS_INTEL)
00231 /* Intel C++ */
00232 # if (__INTEL_COMPILER < 600)
00233 #  error Versions of Intel C++ prior to 6.0 are not supported by the COMSTL libraries
00234 # endif /* __INTEL_COMPILER */
00235 
00236 #elif defined(__STLSOFT_COMPILER_IS_MWERKS)
00237 /* Metrowerks C++ */
00238 # if (__MWERKS__ & 0xFF00) < 0x2400
00239 #  error Versions of Metrowerks CodeWarrior C++ prior to 7.0 are not supported by the COMSTL libraries
00240 # endif /* __MWERKS__ */
00241 
00242 #elif defined(__STLSOFT_COMPILER_IS_MSVC)
00243 /* Visual C++ */
00244 # if _MSC_VER < 1020
00245 #  error Versions of Visual C++ prior to 4.2 are not supported by the COMSTL libraries
00246 # endif /* _MSC_VER */
00247 
00248 #else
00249 /* No recognised compiler */
00250 # ifdef _STLSOFT_FORCE_ANY_COMPILER
00251 #  define _COMSTL_COMPILER_IS_UNKNOWN
00252 #  ifdef _STLSOFT_COMPILE_VERBOSE
00253 #   pragma message("Compiler is unknown to COMSTL")
00254 #  endif /* _STLSOFT_COMPILE_VERBOSE */
00255 # else
00256 #  error Currently only Borland C++, Comeau, Digital Mars C/C++, Intel C/C++, Metrowerks CodeWarrior C/C++ and Visual C++ compilers are supported by the COMSTL libraries
00257 # endif /* _STLSOFT_FORCE_ANY_COMPILER */
00258 #endif /* compiler tag */
00259 
00260 /* 
00261  * Debugging
00262  *
00263  * The macro comstl_assert provides standard debug-mode assert functionality.
00264  */
00265 
00269 #define comstl_assert(expr)                 stlsoft_assert(expr)
00270 
00275 #define comstl_message_assert(msg, expr)    stlsoft_message_assert(msg, expr)
00276 
00280 #define comstl_static_assert(expr)          stlsoft_static_assert(expr)
00281 
00282 /* 
00283  * Compiler language feature support
00284  */
00285 
00286 /* DCOM support
00287  *
00288  * Since some COM APIs are only available, at compile time, when DCOM is
00289  * explicitly discriminated (for Windows this is via _WIN32_WINNT >= 0x0400 or
00290  * presence of _WIN32_DCOM), this must be determined.
00291  *
00292  * Override and always support DCOM by defining _COMSTL_DCOM
00293  *
00294  * Prevent DCOM support by defining _COMSTL_NO_DCOM
00295  *
00296  */
00297 
00298 #ifdef __COMSTL_CF_DCOM_SUPPORT
00299 #undef __COMSTL_CF_DCOM_SUPPORT
00300 #endif /* __COMSTL_CF_DCOM_SUPPORT */
00301 
00302 #if !defined(_COMSTL_NO_DCOM) && \
00303     (   (_WIN32_WINNT >= 0x0400) || \
00304         defined(_WIN32_DCOM) || \
00305         defined(_COMSTL_DCOM))
00306 # define __COMSTL_CF_DCOM_SUPPORT
00307 #endif /* _WIN32_WINNT >= 0x0400 || _WIN32_DCOM */
00308 
00309 /* 
00310  * Namespace
00311  *
00312  * The COMSTL components are contained within the comstl namespace. This is
00313  * usually an alias for stlsoft::comstl_project.
00314  *
00315  * When compilers support namespaces they are defined by default. They can be
00316  * undefined using a cascasing system, as follows:
00317  *
00318  * If _STLSOFT_NO_NAMESPACES is defined, then _COMSTL_NO_NAMESPACES is defined.
00319  *
00320  * If _COMSTL_NO_NAMESPACES is defined, then _COMSTL_NO_NAMESPACE is defined.
00321  *
00322  * If _COMSTL_NO_NAMESPACE is defined, then the COMSTL constructs are defined
00323  * in the global scope.
00324  *
00325  * If _STLSOFT_NO_NAMESPACES, _COMSTL_NO_NAMESPACES and _COMSTL_NO_NAMESPACE are
00326  * all undefined but the symbol _STLSOFT_NO_NAMESPACE is defined (whence the
00327  * namespace stlsoft does not exist), then the COMSTL constructs are defined
00328  * within the comstl namespace. The definition matrix is as follows:
00329  *
00330  * _STLSOFT_NO_NAMESPACE    _COMSTL_NO_NAMESPACE    comstl definition
00331  * ---------------------    --------------------    -----------------
00332  *  not defined              not defined             = stlsoft::comstl_project
00333  *  not defined              defined                 not defined
00334  *  defined                  not defined             comstl
00335  *  defined                  defined                 not defined
00336  *
00337  *
00338  *
00339  * The macro comstl_ns_qual() macro can be used to refer to elements in the
00340  * COMSTL libraries irrespective of whether they are in the
00341  * stlsoft::comstl_project (or comstl) namespace or in the global namespace.
00342  *
00343  * Furthermore, some compilers do not support the standard library in the std
00344  * namespace, so the comstl_ns_qual_std() macro can be used to refer to elements
00345  * in the COMSTL libraries irrespective of whether they are in the std namespace
00346  * or in the global namespace.
00347  */
00348 
00349 /* No STLSoft namespaces means no COMSTL namespaces */
00350 #ifdef _STLSOFT_NO_NAMESPACES
00351 # define _COMSTL_NO_NAMESPACES
00352 #endif /* _STLSOFT_NO_NAMESPACES */
00353 
00354 /* No COMSTL namespaces means no comstl namespace */
00355 #ifdef _COMSTL_NO_NAMESPACES
00356 # define _COMSTL_NO_NAMESPACE
00357 #endif /* _COMSTL_NO_NAMESPACES */
00358 
00359 #ifndef _COMSTL_NO_NAMESPACE
00360 # if defined(_STLSOFT_NO_NAMESPACE) || \
00361      defined(__STLSOFT_DOCUMENTATION_SKIP_SECTION)
00362 /* There is no stlsoft namespace, so must define ::comstl */
00365 namespace comstl
00366 {
00367 # else
00368 /* Define stlsoft::comstl_project */
00369 
00370 namespace stlsoft
00371 {
00372 
00373 namespace comstl_project
00374 {
00375 
00376 # endif /* _STLSOFT_NO_NAMESPACE */
00377 #else
00378 stlsoft_ns_using(move_lhs_from_rhs)
00379 #endif /* !_COMSTL_NO_NAMESPACE */
00380 
00383 
00386 
00387 #ifndef _COMSTL_NO_NAMESPACE
00388 # define comstl_ns_qual(x)          ::comstl::x
00389 # define comstl_ns_using(x)         using ::comstl::x;
00390 #else
00391 # define comstl_ns_qual(x)          x
00392 # define comstl_ns_using(x)
00393 #endif /* !_COMSTL_NO_NAMESPACE */
00394 
00397 
00400 
00401 #ifdef __STLSOFT_CF_std_NAMESPACE
00402 # define comstl_ns_qual_std(x)      ::std::x
00403 # define comstl_ns_using_std(x)     using ::std::x;
00404 #else
00405 # define comstl_ns_qual_std(x)      x
00406 # define comstl_ns_using_std(x)
00407 #endif /* !__STLSOFT_CF_std_NAMESPACE */
00408 
00409 /* 
00410  * Typedefs
00411  *
00412  * The COMSTL uses a number of typedefs to aid in compiler-independence in the
00413  * libraries' main code.
00414  */
00415 
00416 typedef stlsoft_ns_qual(ss_char_a_t)        cs_char_a_t;    
00417 typedef stlsoft_ns_qual(ss_char_w_t)        cs_char_w_t;    
00418 typedef OLECHAR                             cs_char_o_t;    
00419 typedef stlsoft_ns_qual(ss_sint8_t)         cs_sint8_t;     
00420 typedef stlsoft_ns_qual(ss_uint8_t)         cs_uint8_t;     
00421 typedef stlsoft_ns_qual(ss_int16_t)         cs_int16_t;     
00422 typedef stlsoft_ns_qual(ss_sint16_t)        cs_sint16_t;    
00423 typedef stlsoft_ns_qual(ss_uint16_t)        cs_uint16_t;    
00424 typedef stlsoft_ns_qual(ss_int32_t)         cs_int32_t;     
00425 typedef stlsoft_ns_qual(ss_sint32_t)        cs_sint32_t;    
00426 typedef stlsoft_ns_qual(ss_uint32_t)        cs_uint32_t;    
00427 #ifdef STLSOFT_CF_64BIT_INT_SUPPORT
00428 typedef stlsoft_ns_qual(ss_int64_t)         cs_int64_t;     
00429 typedef stlsoft_ns_qual(ss_sint64_t)        cs_sint64_t;    
00430 typedef stlsoft_ns_qual(ss_uint64_t)        cs_uint64_t;    
00431 #endif /* STLSOFT_CF_64BIT_INT_SUPPORT */
00432 typedef stlsoft_ns_qual(ss_int_t)           cs_int_t;       
00433 typedef stlsoft_ns_qual(ss_sint_t)          cs_sint_t;      
00434 typedef stlsoft_ns_qual(ss_uint_t)          cs_uint_t;      
00435 typedef stlsoft_ns_qual(ss_long_t)          cs_long_t;      
00436 typedef stlsoft_ns_qual(ss_bool_t)          cs_bool_t;      
00437 typedef DWORD                               cs_dword_t;     
00438 typedef stlsoft_ns_qual(ss_size_t)          cs_size_t;      
00439 typedef stlsoft_ns_qual(ss_ptrdiff_t)       cs_ptrdiff_t;   
00440 typedef stlsoft_ns_qual(ss_streampos_t)     cs_streampos_t; 
00441 typedef stlsoft_ns_qual(ss_streamoff_t)     cs_streamoff_t; 
00442 
00443 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00444 /* 
00445  * Values
00446  *
00447  * Since the boolean type may not be supported natively on all compilers, the
00448  * values of true and false may also not be provided. Hence the values of
00449  * cs_true_v and cs_false_v are defined, and are used in all code.
00450  */
00451 
00452 #define cs_true_v       ss_true_v
00453 #define cs_false_v      ss_false_v
00454 
00455 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00456 /* 
00457  * Code modification macros
00458  */
00459 
00460 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00461 /* Exception signatures. */
00462 #define comstl_throw_0()                                stlsoft_throw_0()
00463 #define comstl_throw_1(x1)                              stlsoft_throw_1(x1)
00464 #define comstl_throw_2(x1, x2)                          stlsoft_throw_2(x1, x2)
00465 #define comstl_throw_3(x1, x2, x3)                      stlsoft_throw_3(x1, x2, x3)
00466 #define comstl_throw_4(x1, x2, x3, x4)                  stlsoft_throw_4(x1, x2, x3, x4)
00467 #define comstl_throw_5(x1, x2, x3, x4, x5)              stlsoft_throw_5(x1, x2, x3, x4, x5)
00468 #define comstl_throw_6(x1, x2, x3, x4, x5, x6)          stlsoft_throw_6(x1, x2, x3, x4, x5, x6)
00469 #define comstl_throw_7(x1, x2, x3, x4, x5, x6, x7)      stlsoft_throw_7(x1, x2, x3, x4, x5, x6, x7)
00470 #define comstl_throw_8(x1, x2, x3, x4, x5, x6, x7, x8)  stlsoft_throw_8(x1, x2, x3, x4, x5, x6, x7, x8)
00471 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00472 
00474 #define comstl_num_elements(ar)                         stlsoft_num_elements(ar)
00475 
00477 #define comstl_destroy_instance(t, _type, p)            stlsoft_destroy_instance(t, _type, p)
00478 
00480 #define comstl_gen_opaque(_htype)                       stlsoft_gen_opaque(_htype)
00481 
00482 /* 
00483 
00484 #ifndef _COMSTL_NO_NAMESPACE
00485 # if defined(_STLSOFT_NO_NAMESPACE) || \
00486      defined(__STLSOFT_DOCUMENTATION_SKIP_SECTION)
00487 } // namespace comstl
00488 # else
00489 } // namespace comstl_project
00490 } // namespace stlsoft
00491 namespace comstl = ::stlsoft::comstl_project;
00492 # endif /* _STLSOFT_NO_NAMESPACE */
00493 #endif /* !_COMSTL_NO_NAMESPACE */
00494 
00495 /* 
00496 
00497 #endif /* COMSTL_INCL_H_COMSTL */
00498 
00499 /*