###

# Boost.Python

## Header <boost/python/return_opaque_pointer.hpp>

## Contents

Classes
  Class `return_opaque_pointer`
    Class `return_opaque_pointer` synopsis
    Class `return_opaque_pointer` metafunctions
Example
See Also

## Classes

### Class `return_opaque_pointer`

`return_opaque_pointer` is a model of ResultConverterGenerator which can be used to wrap C++ functions returning pointers to undefined types such that the return value is copied into a new Python object.

In addition to specifying the `return_opaque_pointer` policy the `BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID` macro must be used to define specializations for the type_id function on the type pointed to by returned pointer.

#### Class `return_opaque_pointer` synopsis

    namespace boost { namespace python
    {
        struct return_opaque_pointer
        {
            template <class R> struct apply;
        };
    }}

#### Class `return_opaque_pointer` metafunctions

    template <class R> struct apply

Returns: `typedef detail::opaque_conversion_holder<R> type;`

## Example

### C++ Module Definition

    # include <boost/python/return_opaque_pointer.hpp>
    # include <boost/python/def.hpp>
    # include <boost/python/module.hpp>
    # include <boost/python/return_value_policy.hpp>

    typedef struct opaque_ *opaque;

    opaque the_op   = ((opaque) 0x47110815);

    opaque get () { return the_op; }
    void use (opaque op) {
        if (op != the_op)
    	throw std::runtime_error (std::string ("failed"));
    }

    void failuse (opaque op) {
        if (op == the_op)
    	throw std::runtime_error (std::string ("success"));
    }

    BOOST_PYTHON_OPAQUE_SPECIALIZED_TYPE_ID(opaque_)

    namespace bpl = boost::python;

    BOOST_PYTHON_MODULE(opaque_ext)
    {
        bpl::def (
            "get", &::get, bpl::return_value_policy<bpl::return_opaque_pointer>());
        bpl::def ("use", &::use);
        bpl::def ("failuse", &::failuse);
    }

### Python Code

    """
    >>> from opaque_ext import *
    >>> #
    >>> # Check for correct conversion
    >>> use(get())
    >>> failuse(get())
    Traceback (most recent call last):
            ...
    RuntimeError: success
    >>> #
    >>> # Check that there is no conversion from integers ...
    >>> use(0)
    Traceback (most recent call last):
            ...
    TypeError: bad argument type for built-in operation
    >>> #
    >>> # ... and from strings to opaque objects
    >>> use("")
    Traceback (most recent call last):
            ...
    TypeError: bad argument type for built-in operation
    """
    def run(args = None):
        import sys
        import doctest

        if args is not None:
            sys.argv = args
        return doctest.testmod(sys.modules.get(__name__))

    if __name__ == '__main__':
        print "running..."
        import sys
        sys.exit(run()[0])

## See Also

opaque_pointer_converter

Revised 28 January, 2003

© Copyright 2003 Haufe Mediengruppe. All Rights Reserved.