path: root/libshiboken/basewrapper.h

/*
 * This file is part of the Shiboken Python Bindings Generator project.
 *
 * Copyright (C) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).
 *
 * Contact: PySide team <contact@pyside.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#ifndef BASEWRAPPER_H
#define BASEWRAPPER_H

#include <Python.h>
#include "python25compat.h"
#include "bindingmanager.h"
#include <list>
#include <map>
#include <string>

extern "C"
{

struct SbkObjectPrivate;

/// Base Python object for all the wrapped C++ classes.
struct LIBSHIBOKEN_API SbkObject
{
    PyObject_HEAD
    /// Instance dictionary.
    PyObject* ob_dict;
    /// List of weak references
    PyObject* weakreflist;
    SbkObjectPrivate* d;
};


/// Dealloc the python object \p pyObj and the C++ object represented by it.
LIBSHIBOKEN_API void SbkDeallocWrapper(PyObject* pyObj);
LIBSHIBOKEN_API void SbkDeallocWrapperWithPrivateDtor(PyObject* self);

struct SbkBaseType;

/// Function signature for the multiple inheritance information initializers that should be provided by classes with multiple inheritance.
typedef int* (*MultipleInheritanceInitFunction)(const void*);

/**
 *   Special cast function is used to correctly cast an object when it's
 *   part of a multiple inheritance hierarchy.
 *   The implementation of this function is auto generated by the generator and you don't need to care about it.
 */
typedef void* (*SpecialCastFunction)(void*, SbkBaseType*);
typedef void* (*ObjectCopierFunction)(const void*);
typedef SbkBaseType* (*TypeDiscoveryFunc)(void*, SbkBaseType*);

typedef void* (*ExtendedToCppFunc)(PyObject*);
typedef bool (*ExtendedIsConvertibleFunc)(PyObject*);

// Used in userdata dealloc function
typedef void (*DeleteUserDataFunc)(void*);

typedef void (*ObjectDestructor)(void*);

extern LIBSHIBOKEN_API PyTypeObject SbkBaseType_Type;
extern LIBSHIBOKEN_API SbkBaseType SbkObject_Type;


struct SbkBaseTypePrivate;
/// PyTypeObject extended with C++ multiple inheritance information.
struct LIBSHIBOKEN_API SbkBaseType
{
    PyHeapTypeObject super;
    SbkBaseTypePrivate* d;
};

LIBSHIBOKEN_API PyObject* SbkObjectTpNew(PyTypeObject* subtype, PyObject*, PyObject*);

} // extern "C"

namespace Shiboken
{

/**
*   Init shiboken library.
*/
LIBSHIBOKEN_API void init();


/// Delete the class T allocated on \p cptr.
template<typename T>
void callCppDestructor(void* cptr)
{
    delete reinterpret_cast<T*>(cptr);
}

LIBSHIBOKEN_API bool        importModule(const char* moduleName, PyTypeObject*** cppApiPtr);
LIBSHIBOKEN_API void        setErrorAboutWrongArguments(PyObject* args, const char* funcName, const char** cppOverloads);

namespace BaseType {

/**
*   Returns true if the object is an instance of a type created by the Shiboken generator.
*/
LIBSHIBOKEN_API bool        checkType(PyTypeObject* pyObj);

/**
*   Returns true if this object is an instance of an user defined type derived from an Shiboken type.
*/
LIBSHIBOKEN_API bool        isUserType(PyTypeObject* pyObj);

/**
*   Returns true if the constructor of \p ctorType can be called for a instance of type \p myType.
*   \note This function set a python error when returning false.
*/
LIBSHIBOKEN_API bool        canCallConstructor(PyTypeObject* myType, PyTypeObject* ctorType);

/**
 * Call copy function for the object type
 **/
LIBSHIBOKEN_API void*       copy(SbkBaseType* self, const void *obj);
LIBSHIBOKEN_API void        setCopyFunction(SbkBaseType* self, ObjectCopierFunction func);

LIBSHIBOKEN_API void        setExternalCppConversionFunction(SbkBaseType* self, ExtendedToCppFunc func);
LIBSHIBOKEN_API void        setExternalIsConvertibleFunction(SbkBaseType* self, ExtendedIsConvertibleFunc func);
LIBSHIBOKEN_API bool        hasExternalCppConversions(SbkBaseType* self);
LIBSHIBOKEN_API bool        isExternalConvertible(SbkBaseType* self, PyObject* obj);
LIBSHIBOKEN_API void*       callExternalCppConversion(SbkBaseType* self, PyObject* obj);

LIBSHIBOKEN_API bool        hasCast(SbkBaseType* self);
LIBSHIBOKEN_API void*       cast(SbkBaseType* self, SbkObject* obj, PyTypeObject* target);
LIBSHIBOKEN_API void        setCastFunction(SbkBaseType* self, SpecialCastFunction func);

LIBSHIBOKEN_API void        setOriginalName(SbkBaseType* self, const char* name);
LIBSHIBOKEN_API const char* getOriginalName(SbkBaseType* self);

LIBSHIBOKEN_API void        setTypeDiscoveryFunction(SbkBaseType* self, TypeDiscoveryFunc func);
LIBSHIBOKEN_API TypeDiscoveryFunc getTypeDiscoveryFunction(SbkBaseType* self);

LIBSHIBOKEN_API void        copyMultimpleheritance(SbkBaseType* self, SbkBaseType* other);
LIBSHIBOKEN_API void        setMultipleIheritanceFunction(SbkBaseType* self, MultipleInheritanceInitFunction func);
LIBSHIBOKEN_API MultipleInheritanceInitFunction getMultipleIheritanceFunction(SbkBaseType* self);

LIBSHIBOKEN_API void        setDestructorFunction(SbkBaseType* self, ObjectDestructor func);

LIBSHIBOKEN_API void        initPrivateData(SbkBaseType* self);
}

namespace Wrapper {

/**
*   Returns true if the object is an instance of a type created by the Shiboken generator.
*/
LIBSHIBOKEN_API bool        checkType(PyObject* pyObj);
LIBSHIBOKEN_API bool        isUserType(PyObject* pyObj);


LIBSHIBOKEN_API PyObject*   newObject(SbkBaseType* instanceType,
                                      void* cptr,
                                      bool hasOwnership = true,
                                      bool isExactType = false,
                                      const char* typeName = 0);

LIBSHIBOKEN_API void        setValidCpp(SbkObject* pyObj, bool value);
LIBSHIBOKEN_API void        setHasCppWrapper(SbkObject* pyObj, bool value);
LIBSHIBOKEN_API bool        hasCppWrapper(SbkObject* pyObj);

LIBSHIBOKEN_API bool        hasOwnership(SbkObject* pyObj);
LIBSHIBOKEN_API void        getOwnership(PyObject* pyObj);
LIBSHIBOKEN_API void        getOwnership(SbkObject* pyObj);
LIBSHIBOKEN_API void        releaseOwnership(PyObject* pyObj);
LIBSHIBOKEN_API void        releaseOwnership(SbkObject* pyObj);

LIBSHIBOKEN_API bool        hasParentInfo(SbkObject* pyObj);

/**
 *   Get the C++ pointer of type \p desiredType from a Python object.
 */
LIBSHIBOKEN_API void*       cppPointer(SbkObject* pyObj, PyTypeObject* desiredType);

/**
 *   Set the C++ pointer of type \p desiredType of a Python object.
 */
LIBSHIBOKEN_API bool        setCppPointer(SbkObject* sbkObj, PyTypeObject* desiredType, void* cptr);

/**
 * Returns false and sets a Python RuntimeError if the Python wrapper is not marked as valid.
 */
LIBSHIBOKEN_API bool        isValid(PyObject* wrapper);

/**
*   Set the parent of \p child to \p parent.
*   When an object dies, all their children, granchildren, etc, are tagged as invalid.
*   \param parent the parent object, if null, the child will have no parents.
*   \param child the child.
*/
LIBSHIBOKEN_API void        setParent(PyObject* parent, PyObject* child);

/**
*   Remove this child from their parent, if any.
*   \param child the child.
*/
LIBSHIBOKEN_API void        removeParent(SbkObject* child, bool giveOwnershipBack = true, bool keepReferenc = false);

/**
* \internal This is an internal function called by SbkBaseWrapper_Dealloc, it's exported just for techinical reasons.
* \note Do not call this function inside your bindings.
*/
LIBSHIBOKEN_API void        destroyParentInfo(SbkObject* obj, bool removeFromParent = true);

/**
 * Mark the object as invalid
 */
LIBSHIBOKEN_API void        invalidate(SbkObject* self);

/**
 * Help function can be used to invalida a sequence of object
 **/
LIBSHIBOKEN_API void        invalidate(PyObject* pyobj);

/**
 * Make the object valid again
 */
LIBSHIBOKEN_API void        makeValid(SbkObject* self);

/**
 * Destroy any data in Shiboken structure and c++ pointer if the pyboject has the ownership
 **/
LIBSHIBOKEN_API void        destroy(SbkObject* self);

/**
 *   Get/Set Userdata in type class
 */
LIBSHIBOKEN_API void        setTypeUserData(SbkObject* wrapper, void* user_data, DeleteUserDataFunc d_func);
LIBSHIBOKEN_API void*       getTypeUserData(SbkObject* wrapper);

/**
 *   Increments the reference count of the referred Python object.
 *   A previous Python object in the same position identified by the 'key' parameter
 *   will have its reference counter decremented automatically when replaced.
 *   All the kept references should be decremented when the Python wrapper indicated by
 *   'self' dies.
 *   No checking is done for any of the passed arguments, since it is meant to be used
 *   by generated code it is supposed that the generator is correct.
 *   \param self            the wrapper instance that keeps references to other objects.
 *   \param key             a key that identifies the C++ method signature and argument where the referredObject came from.
 *   \parem referredObject  the object whose reference is used by the self object.
 */
LIBSHIBOKEN_API void        keepReference(SbkObject* self, const char* key, PyObject* referredObject, bool append=false);

} // namespace Wrapper

} // namespace Shiboken

#endif // BASEWRAPPER_H