comstl/collections/enumeration_policies.hpp

Go to the documentation of this file.

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/collections/enumeration_policies.hpp
 *
 * Purpose:     Policies for enumerator interface handling.
 *
 * Created:     20th December 2003
 * Updated:     10th August 2009
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2003-2009, 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.
 *
 * ////////////////////////////////////////////////////////////////////// */


#ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES
#define COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MAJOR       6
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MINOR       1
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_REVISION    6
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT        52
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_WATCOM:
[Incompatibilies-end]
 */

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

#ifndef COMSTL_INCL_COMSTL_H_COMSTL
# include <comstl/comstl.h>
#endif /* !COMSTL_INCL_COMSTL_H_COMSTL */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER
# include <stlsoft/util/std/iterator_helper.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
# ifndef COMSTL_INCL_COMSTL_ERROR_HPP_EXCEPTIONS
#  include <comstl/error/exceptions.hpp>
# endif /* !COMSTL_INCL_COMSTL_ERROR_HPP_EXCEPTIONS */
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */

/* /////////////////////////////////////////////////////////////////////////
 * 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 */

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

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT

// [[synesis:class:exception: comstl::clone_failure]]
class clone_failure
    : public com_exception
{
public:
    typedef com_exception       parent_class_type;
    typedef clone_failure       class_type;

public:
    ss_explicit_k clone_failure(HRESULT hr)
        : parent_class_type(hr)
    {}

public:
#if defined(STLSOFT_COMPILER_IS_DMC)
    char const  *what() const throw()
#else /* ? compiler */
    char const  *what() const stlsoft_throw_0()
#endif /* compiler */
    {
        return "Request to clone enumerator failed";
    }

private:
    class_type& operator =(class_type const&);
};

#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */


struct noncloneable_enumerator_tag
{};

struct cloneable_enumerator_tag
{};

struct repeatable_enumerator_tag
    : public cloneable_enumerator_tag
{};



template<ss_typename_param_k I>
struct input_cloning_policy
    : public noncloneable_enumerator_tag
{
public:
    typedef I                                       interface_type;
    typedef interface_type*                         value_type;
    typedef comstl_ns_qual_std(input_iterator_tag)  iterator_tag_type;

public:
    static interface_type *get_working_instance(interface_type *root)
    {
        COMSTL_ASSERT(NULL != root);

        root->AddRef();

        return root;
    }

    static interface_type *share(interface_type *src)
    {
        COMSTL_ASSERT(NULL != src);

        src->AddRef();

        return src;
    }
    static cs_bool_t clone(interface_type *src, interface_type **pdest)
    {
        COMSTL_ASSERT(NULL != src);
        COMSTL_ASSERT(NULL != pdest);
        STLSOFT_SUPPRESS_UNUSED(src);

        *pdest = NULL;

        return false;
    }
};

template<ss_typename_param_k I>
struct cloneable_cloning_policy
    : public cloneable_enumerator_tag
{
public:
    typedef I                                       interface_type;
    typedef interface_type*                         value_type;
    typedef comstl_ns_qual_std(input_iterator_tag)  iterator_tag_type;

public:
    static interface_type *get_working_instance(interface_type *root)
    {
        COMSTL_ASSERT(NULL != root);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(root)->Clone(&ret);

        if(FAILED(hr))
        {
            ret = NULL;
        }

        return ret;
    }

    static interface_type *share(interface_type *src)
    {
        COMSTL_ASSERT(NULL != src);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(src)->Clone(&ret);

        if(FAILED(hr))
        {
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
            STLSOFT_THROW_X(clone_failure(hr));
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
            ret = NULL;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
        }

        return ret;
    }
    static cs_bool_t clone(interface_type *src, interface_type **pdest)
    {
        COMSTL_ASSERT(NULL != src);
        COMSTL_ASSERT(NULL != pdest);

        *pdest = share(src);

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
        COMSTL_ASSERT(NULL != *pdest);

        return true;
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
        return NULL != *pdest;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
    }
};

template<ss_typename_param_k I>
struct forward_cloning_policy
    : public repeatable_enumerator_tag
{
public:
    typedef I                                           interface_type;
    typedef interface_type*                             value_type;
    typedef comstl_ns_qual_std(forward_iterator_tag)    iterator_tag_type;

public:
    static interface_type *get_working_instance(interface_type *root)
    {
        COMSTL_ASSERT(NULL != root);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(root)->Clone(&ret);

        if(FAILED(hr))
        {
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
            STLSOFT_THROW_X(clone_failure(hr));
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
            ret = NULL;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
        }

        return ret;
    }

    static interface_type *share(interface_type *src)
    {
        COMSTL_ASSERT(NULL != src);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(src)->Clone(&ret);

        if(FAILED(hr))
        {
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
            STLSOFT_THROW_X(clone_failure(hr));
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
            ret = NULL;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
        }

        return ret;
    }
    static cs_bool_t clone(interface_type *src, interface_type **pdest)
    {
        COMSTL_ASSERT(NULL != src);
        COMSTL_ASSERT(NULL != pdest);

        *pdest = share(src);

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
        COMSTL_ASSERT(NULL != *pdest);

        return true;
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
        return NULL != *pdest;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
    }
};

template <ss_typename_param_k P>
struct value_policy_adaptor
    : public P
{
public:
    typedef ss_typename_type_k P::value_type    value_type;

public:
    struct init_element
    {
        void operator ()(value_type &v) const
        {
            P::init(&v);
        }
    };
    struct copy_element
    {
        void operator ()(value_type &dest, value_type const& src) const
        {
            P::copy(&dest, &src);
        }
    };
    struct clear_element
    {
        void operator ()(value_type &v) const
        {
            P::clear(&v);
        }
    };
};

template <ss_typename_param_k P>
struct policy_adaptor
    : public value_policy_adaptor<P>
{
public:
    typedef ss_typename_type_k P::value_type    value_type;
};

template <ss_typename_param_k CI>
struct new_enum_property_policy
{
public:
    typedef CI          collection_interface;

public:
    static HRESULT acquire(collection_interface *pcoll, LPUNKNOWN *ppunkEnum)
    {
        COMSTL_ASSERT(NULL != pcoll);
        COMSTL_ASSERT(NULL != ppunkEnum);

        // If the compiler complains here that your interface does not have the
        // get__NewEnum method, then:
        //
        // - you're passing a pure IDispatch interface, so you need to use
        //    new_enum_by_dispid_policy
        // - you're passing a collection interface that defines _NeWEnum as a
        //    method, so you need to use new_enum_method_policy
        // - you're passing the wrong interface. Check your code to ensure
        //    you've not used the wrong interface to specialise
        //    comstl::collection_sequence.
        return pcoll->get__NewEnum(ppunkEnum);
    }
};

template <ss_typename_param_k CI>
struct new_enum_method_policy
{
public:
    typedef CI          collection_interface;

public:
    static HRESULT acquire(collection_interface *pcoll, LPUNKNOWN *ppunkEnum)
    {
        COMSTL_ASSERT(NULL != pcoll);
        COMSTL_ASSERT(NULL != ppunkEnum);

        return pcoll->_NewEnum(ppunkEnum);
    }
};

template <ss_typename_param_k CI>
struct new_enum_by_dispid_policy
{
public:
    typedef CI          collection_interface;

public:
    static HRESULT acquire(collection_interface *pcoll, LPUNKNOWN *ppunkEnum)
    {
        COMSTL_ASSERT(NULL != pcoll);
        COMSTL_ASSERT(NULL != ppunkEnum);

        LPDISPATCH  pdisp;
        HRESULT     hr  =   pcoll->QueryInterface(IID_IDispatch, reinterpret_cast<void**>(&pdisp));

        if(SUCCEEDED(hr))
        {
            DISPPARAMS  params;
            UINT        argErrIndex;
            VARIANT     result;

            ::memset(&params, 0, sizeof(params));
            ::VariantInit(&result);

            hr = pdisp->Invoke( DISPID_NEWENUM
                            ,   IID_NULL
                            ,   LOCALE_USER_DEFAULT
                            ,   DISPATCH_METHOD | DISPATCH_PROPERTYGET
                            ,   &params
                            ,   &result
                            ,   NULL
                            ,   &argErrIndex);

            pdisp->Release();

            if(SUCCEEDED(hr))
            {
                hr = ::VariantChangeType(&result, &result, 0, VT_UNKNOWN);

                if(SUCCEEDED(hr))
                {
                    if(NULL == result.punkVal)
                    {
                        hr = E_UNEXPECTED;
                    }
                    else
                    {
                        *ppunkEnum = result.punkVal;

                        (*ppunkEnum)->AddRef();
                    }
                }

                ::VariantClear(&result);
            }
        }

        return hr;
    }
};

/* ////////////////////////////////////////////////////////////////////// */

#ifndef _COMSTL_NO_NAMESPACE
# if defined(_STLSOFT_NO_NAMESPACE) || \
     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
} // namespace comstl
# else
} // namespace stlsoft::comstl_project
} // namespace stlsoft
# endif /* _STLSOFT_NO_NAMESPACE */
#endif /* !_COMSTL_NO_NAMESPACE */

/* ////////////////////////////////////////////////////////////////////// */

#endif /* !COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES */

/* ///////////////////////////// end of file //////////////////////////// */

---