interface_cast.hpp

用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、WTL等多种组件

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/interface_cast.hpp (formerly comstl_interface_cast.h)
 *
 * Purpose:     Safe interface casting functions.
 *
 * Created:     25th June 2002
 * Updated:     10th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2002-2006, 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/interface_cast.hpp
///
/// Safe interface casting functions.

#ifndef COMSTL_INCL_COMSTL_HPP_INTERFACE_CAST
#define COMSTL_INCL_COMSTL_HPP_INTERFACE_CAST

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define COMSTL_VER_COMSTL_HPP_INTERFACE_CAST_MAJOR     3
# define COMSTL_VER_COMSTL_HPP_INTERFACE_CAST_MINOR     3
# define COMSTL_VER_COMSTL_HPP_INTERFACE_CAST_REVISION  1
# define COMSTL_VER_COMSTL_HPP_INTERFACE_CAST_EDIT      88
#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_interface_cast.h is not compatible with Visual C++ 5.0 or earlier
#endif /* compiler */

#ifndef COMSTL_INCL_COMSTL_H_REFCOUNT_FUNCTIONS
# include <comstl/refcount_functions.h>     // for safe_addref(), safe_release()
#endif /* !COMSTL_INCL_COMSTL_H_REFCOUNT_FUNCTIONS */
#ifndef COMSTL_INCL_COMSTL_HPP_INTERFACE_TRAITS
# include <comstl/interface_traits.hpp>     // for IID_traits
#endif /* !COMSTL_INCL_COMSTL_HPP_INTERFACE_TRAITS */
#ifndef COMSTL_INCL_COMSTL_HPP_BAD_INTERFACE_CAST
# include <comstl/bad_interface_cast.hpp>   // for bad_interface_cast
#endif /* !COMSTL_INCL_COMSTL_HPP_BAD_INTERFACE_CAST */
#ifndef STLSOFT_INCL_STLSOFT_HPP_OPERATOR_BOOL
# include <stlsoft/operator_bool.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_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
 */

/// A null exception generating type
// [[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
    }
};

/// A null exception generating type
// [[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)
    {
        throw bad_interface_cast(riid, hr);
    }
};

/// A function object that calls Release() on the interface
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);
    }
};

/// A function object that does not call Release() on the interface
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

/// Interface pointer traits
///
/// \param I The interface type
template <ss_typename_param_k I>
struct interface_pointer_traits;

/// A specialisation for pointers only
template <ss_typename_param_k I>
struct interface_pointer_traits<I*>
{
    typedef I   interface_type;
};

/// A veneer interface that hides the AddRef() and Release() methods
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
 */

/// Base class for the interface cast classes
///
/// 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
{
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;

// Construction
protected:
    /// Constructor that attempts the speculative cast
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_CTOR_SUPPORT
    template <ss_typename_param_k J>
    ss_explicit_k interface_cast_base(J &j)
        : m_pi(do_cast(simple_interface_cast(j)))
    {}
#else /* ? STLSOFT_CF_MEMBER_TEMPLATE_CTOR_SUPPORT */
    ss_explicit_k interface_cast_base(LPUNKNOWN punk)
        : m_pi(do_cast(punk))
    {}
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_CTOR_SUPPORT */

    /// Constructor that directly casts (without calling QueryInterface())
    ss_explicit_k interface_cast_base(interface_pointer_type pi)
        : m_pi(pi)
    {
        addref(m_pi);
    }

protected:
    /// Releases the acquired interface pointer according to the \c release_type policy
    ~interface_cast_base() stlsoft_throw_0()
    {
        if(NULL != m_pi)
        {
            release_type()(m_pi);
        }
    }

// Implementation
protected:
    /// Perform the cast, throwing the \c exception_policy_type's \c thrown_type if the
    /// requested interface cannot be acquired.
    ///
    /// \param punk The interface pointer to cast
    /// \return The converted interface pointer
    static interface_pointer_type do_cast(LPUNKNOWN punk) stlsoft_throw_1(thrown_type)
    {
        interface_pointer_type  pi;

        if(NULL == punk)
        {
            pi = NULL;
        }
        else
        {
            REFIID  iid =   IID_traits<interface_pointer_type>().iid();
            HRESULT hr  =   punk->QueryInterface(iid, reinterpret_cast<void**>(&pi));

            if(FAILED(hr))
            {
                exception_policy_type()(hr, iid);

                pi = NULL;
            }
        }

        return pi;
    }

    /// Returns a non-mutating reference to the acquired interface pointer
    interface_pointer_type const &get_pointer_()
    {
        return m_pi;
    }

    /// Returns a copy of the acquired interface pointer
    interface_pointer_type get_pointer_() const
    {
        return m_pi;
    }

// Members