interface_cast.hpp

新版本TR1的stl

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/conversion/interface_cast.hpp
 *
 * Purpose:     Safe interface casting functions.
 *
 * Created:     25th June 2002
 * Updated:     12th March 2007
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2002-2007, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


/** \file comstl/conversion/interface_cast.hpp
 *
 * \brief [C++ only] Definition of the
 *   comstl::interface_cast,
 *   comstl::interface_cast_test
 *  and
 *   comstl::try_interface_cast
 *  cast functions
 *  and the
 *   comstl::interface_cast_addref
 *  and
 *   comstl::interface_cast_noaddref
 *  cast classes.
 *   (\ref group__library__conversion "Conversion" Library).
 */

#ifndef COMSTL_INCL_COMSTL_CONVERSION_HPP_INTERFACE_CAST
#define COMSTL_INCL_COMSTL_CONVERSION_HPP_INTERFACE_CAST

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define COMSTL_VER_COMSTL_CONVERSION_HPP_INTERFACE_CAST_MAJOR      5
# define COMSTL_VER_COMSTL_CONVERSION_HPP_INTERFACE_CAST_MINOR      2
# define COMSTL_VER_COMSTL_CONVERSION_HPP_INTERFACE_CAST_REVISION   2
# define COMSTL_VER_COMSTL_CONVERSION_HPP_INTERFACE_CAST_EDIT       112
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Compatibility
 */

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_MSVC: _MSC_VER<1200
[Incompatibilies-end]
 */

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef COMSTL_INCL_COMSTL_H_COMSTL
# include <comstl/comstl.h>
#endif /* !COMSTL_INCL_COMSTL_H_COMSTL */

#if defined(STLSOFT_COMPILER_IS_MSVC) && \
    _MSC_VER < 1200
# error comstl/conversion/interface_cast.hpp is not compatible with Visual C++ 5.0 or earlier
#endif /* compiler */

#ifndef COMSTL_INCL_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS
# include <comstl/util/refcount_functions.h>
#endif /* !COMSTL_INCL_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS */
#ifndef COMSTL_INCL_COMSTL_UTIL_HPP_INTERFACE_TRAITS
# include <comstl/util/interface_traits.hpp>
#endif /* !COMSTL_INCL_COMSTL_UTIL_HPP_INTERFACE_TRAITS */
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
# ifndef COMSTL_INCL_COMSTL_ERROR_HPP_BAD_INTERFACE_CAST
#  include <comstl/error/bad_interface_cast.hpp>
# endif /* !COMSTL_INCL_COMSTL_ERROR_HPP_BAD_INTERFACE_CAST */
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
#ifndef STLSOFT_INCL_STLSOFT_SMARTPTR_HPP_REF_PTR
# include <stlsoft/smartptr/ref_ptr.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_SMARTPTR_HPP_REF_PTR */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_OPERATOR_BOOL
# include <stlsoft/util/operator_bool.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_OPERATOR_BOOL */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef _COMSTL_NO_NAMESPACE
# if defined(_STLSOFT_NO_NAMESPACE) || \
     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
/* There is no stlsoft namespace, so must define ::comstl */
namespace comstl
{
# else
/* Define stlsoft::comstl_project */

namespace stlsoft
{

namespace comstl_project
{

# endif /* _STLSOFT_NO_NAMESPACE */
#endif /* !_COMSTL_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Functions
 */

// This helper converts from an interface pointer to itself.
//
// It explicitly takes and returns pointer so that it disambiguates from any
// overload that takes an interface wrapper instance by value/reference.
template <ss_typename_param_k I>
inline I *simple_interface_cast(I *pi)
{
    return pi;
}

/* /////////////////////////////////////////////////////////////////////////
 * Functionals
 */

/** \brief A function class that does not throw any exceptions. For use with
 *    comstl::interface_cast_noaddref and comstl::interface_cast_addref cast
 *    classes.
 *
 * \ingroup group__library__conversion
 */
// [[synesis:class:exception-policy: ignore_interface_cast_exception]]
struct ignore_interface_cast_exception
{
public:
    /// The exception type
    struct thrown_type
    {
    };

public:
    /// The function call operator, which does not throw an exception
    ///
    /// \param hr The HRESULT that caused the error
    /// \param riid The REFIID that could not be acquired
    void operator ()(HRESULT hr, REFIID riid) stlsoft_throw_0()
    {
        STLSOFT_SUPPRESS_UNUSED(hr);
        STLSOFT_SUPPRESS_UNUSED(riid);

        // Do nothing
    }
};

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT

/** \brief A function class that throws the 
 *     \link comstl::bad_interface_cast bad_interface_cast\endlink exception
 *     class. For use with
 *    comstl::interface_cast_noaddref and comstl::interface_cast_addref cast
 *    classes.
 *
 * \ingroup group__library__conversion
 */
// [[synesis:class:exception-policy: throw_bad_interface_cast_exception]]
struct throw_bad_interface_cast_exception
{
public:
    /// The exception type
    typedef bad_interface_cast  thrown_type;

public:
    /// The function call operator, which throws the exception
    ///
    /// \param hr The HRESULT that caused the error
    /// \param riid The REFIID that could not be acquired
    void operator ()(HRESULT hr, REFIID riid) stlsoft_throw_1(bad_interface_cast)
    {
        STLSOFT_THROW_X(bad_interface_cast(riid, hr));
    }
};

#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

/** \brief A function class that calls Release() on the interface.  For use with
 *    comstl::interface_cast_noaddref and comstl::interface_cast_addref cast
 *    classes.
 *
 * \ingroup group__library__conversion
 */
template <ss_typename_param_k I>
struct noaddref_release
{
public:
    /// The function call operator, that calls Release() on the interface
    ///
    /// \param pi The interface pointer
    void operator ()(I pi)
    {
        release(pi);
    }
};

/** \brief A function class that does not call Release() on the interface. For use with
 *    comstl::interface_cast_noaddref and comstl::interface_cast_addref cast
 *    classes.
 *
 * \ingroup group__library__conversion
 */
template <ss_typename_param_k I>
struct addref_release
{
public:
    /// The function call operator, which does not call Release() on the interface
    ///
    /// \param pi The interface pointer
    void operator ()(I pi)
    {
        STLSOFT_SUPPRESS_UNUSED(pi);
    }
};

/* /////////////////////////////////////////////////////////////////////////
 * Raw-pointer safety
 *
 * Alas this requires partial template specialisation, so is not available in
 * all environments.
 */

#ifdef STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT

# ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

template <ss_typename_param_k I>
struct interface_pointer_traits;

template <ss_typename_param_k I>
struct interface_pointer_traits<I*>
{
    typedef I   interface_type;
};

# endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \brief A veneer interface that hides the AddRef() and Release() methods.
 *    For use with comstl::interface_cast_noaddref and
 *    comstl::interface_cast_addref cast classes.
 *
 * \ingroup group__library__conversion
 */
template <ss_typename_param_k I>
interface protect_refcount
    : public I
{
private:
    STDMETHOD_(ULONG, AddRef)()
    {
        I   *pi = static_cast<I*>(this);

        return pi->AddRef();
    }
    STDMETHOD_(ULONG, Release)()
    {
        I   *pi = static_cast<I*>(this);

        return pi->Release();
    }
};

#endif /* STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT */

/* /////////////////////////////////////////////////////////////////////////
 * Classes
 */

/** \brief Base class for the interface cast classes
 *    comstl::interface_cast_noaddref and comstl::interface_cast_addref.
 *
 * \ingroup group__library__conversion
 *
 * This class serves only as a base, and cannot be used in isolation
 *
 * \param I The interface pointer type
 * \param R The release type
 * \param X The exception type
 */
// [[synesis:class:implementation: comstl::interface_cast_base]]
template<   ss_typename_param_k I
        ,   ss_typename_param_k R
        ,   ss_typename_param_k X
        >
class interface_cast_base
{
/// \name Member Types
/// @{
public:
    /// The interface pointer type
    typedef I                                                               interface_pointer_type;
#ifdef STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT
    /// The interface type
    typedef ss_typename_type_k interface_pointer_traits<I>::interface_type  interface_type;
#endif /* STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT */
    /// The release type
    typedef R                                                               release_type;
    /// The exception type
    typedef X                                                               exception_policy_type;
    /// The thrown type
    typedef ss_typename_type_k exception_policy_type::thrown_type           thrown_type;
    /// The type of the current parameterisation
    typedef interface_cast_base<I, R, X>                                    class_type;
/// @}

/// \name Member Constants
/// @{
protected:
    enum NullThrowPermission
    {
            allowNull
        ,   throwOnNull
    };
/// @}

/// \name Construction
/// @{
protected: