sipref.txt

这是关于RFC3261实现sip的源代码

%CModule
--------

.. parsed-literal::

    %CModule *name* [*version*]

This directive is used to identify that the library being wrapped is a C
library and to define the name of the module and it's optional version number.

See the `%Module`_ directive for an explanation of the version number.

For example::

    %CModule dbus 1


%ConvertFromTypeCode
--------------------

.. parsed-literal::

    %ConvertFromTypeCode
        *code*
    %End

This directive is used as part of the `%MappedType`_ directive to specify the
handwritten code that converts an instance of a mapped type to a Python
object.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the instance of the mapped type to be converted.  It
    will never be zero as the conversion from zero to ``Py_None`` is handled
    before the handwritten code is called.

PyObject \*sipTransferObj
    This specifies any desired ownership changes to the returned object.  If it
    is ``NULL`` then the ownership should be left unchanged.  If it is
    ``Py_None`` then ownership should be transferred to Python.  Otherwise
    ownership should be transferred to C/C++ and the returned object associated
    with *sipTransferObj*.  The code can choose to interpret these changes in
    any way.  For example, if the code is converting a C++ container of wrapped
    classes to a Python list it is likely that the ownership changes should be
    made to each element of the list.

The handwritten code must explicitly return a ``PyObject *``.  If there was an
error then a Python exception must be raised and ``NULL`` returned.

The following example converts a ``QList<QWidget *>`` instance to a Python
list of ``QWidget`` instances::

    %ConvertFromTypeCode
        PyObject *l;

        // Create the Python list of the correct length.
        if ((l = PyList_New(sipCpp -> size())) == NULL)
            return NULL;

        // Go through each element in the C++ instance and convert it to a
        // wrapped QWidget.
        for (int i = 0; i < sipCpp -> size(); ++i)
        {
            QWidget *w = sipCpp -> at(i);
            PyObject *wobj;

            // Get the Python wrapper for the QWidget instance, creating a new
            // one if necessary, and handle any ownership transfer.
            if ((wobj = sipConvertFromInstance(w, sipClass_QWidget, sipTransferObj)) == NULL)
            {
                // There was an error so garbage collect the Python list.
                Py_DECREF(l);
                return NULL;
            }

            // Add the wrapper to the list.
            PyList_SET_ITEM(l, i, wobj);
        }

        // Return the Python list.
        return l;
    %End


%ConvertToSubClassCode
----------------------

.. parsed-literal::

    %ConvertToSubClassCode
        *code*
    %End

When SIP needs to wrap a C++ class instance it first checks to make sure it
hasn't already done so.  If it has then it just returns a new reference to the
corresponding Python object.  Otherwise it creates a new Python object of the
appropriate type.  In C++ a function may be defined to returned an instance of
a certain class, but can often return a sub-class instead.

This directive is used to specify handwritten code that exploits any available
real-time type information (RTTI) to see if there is a more specific Python
type that can be used when wrapping the C++ instance.  The RTTI may be
provided by the compiler or by the C++ instance itself.

The directive is included in the specification of one of the classes that the
handwritten code handles the type conversion for.  It doesn't matter which
one, but a sensible choice would be the one at the root of that class
hierarchy in the module.

Note that if a class hierarchy extends over a number of modules then this
directive should be used in each of those modules to handle the part of the
hierarchy defined in that module.  SIP will ensure that the different pieces
of code are called in the right order to determine the most specific Python
type to use.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the C++ class instance.

void \*\*sipCppRet
    When the sub-class is derived from more than one super-class then it is
    possible that the C++ address of the instance as the sub-class is
    different to that of the super-class.  If so, then this must be set to the
    C++ address of the instance when cast (usually using ``static_cast``)
    from the super-class to the sub-class.

sipWrapperType \*sipClass
    The handwritten code must set this to the SIP generated Python type object
    that corresponds to the class instance.  (The type object for class
    ``Klass`` is ``sipClass_Klass``.)  If the RTTI of the class instance isn't
    recognised then ``sipClass`` must be set to ``NULL``.

The handwritten code must not explicitly return.

The following example shows the sub-class conversion code for ``QEvent`` based
class hierarchy in PyQt::

    class QEvent
    {
    %ConvertToSubClassCode
        // QEvent sub-classes provide a unique type ID.
        switch (sipCpp -> type())
        {
        case QEvent::Timer:
            sipClass = sipClass_QTimerEvent;
            break;

        case QEvent::KeyPress:
        case QEvent::KeyRelease:
            sipClass = sipClass_QKeyEvent;
            break;

        // Skip the remaining event types the keep the example short.

        default:
            // We don't recognise the type.
            sipClass = NULL;
        }
    %End

        // The rest of the class specification.

    };

The SIP API includes the `sipMapIntToClass()`_ and `sipMapStringToClass()`_
functions that convert integer and string based RTTI to Python type objects
based on ordered lookup tables.


%ConvertToTypeCode
------------------

.. parsed-literal::

    %ConvertToTypeCode
        *code*
    %End

This directive is used to specify the handwritten code that converts a Python
object to a mapped type instance and to handle any ownership transfers.  It is
used as part of the `%MappedType`_ directive and as part of a class
specification.  The code is also called to determine if the Python object is of
the correct type prior to conversion.

When used as part of a class specification it can automatically convert
additional types of Python object.  For example, PyQt uses it in the
specification of the ``QString`` class to allow Python string objects and
Unicode objects to be used wherever ``QString`` instances are expected.

The following variables are made available to the handwritten code:

int \*sipIsErr
    If this is ``NULL`` then the code is being asked to check the type of the
    Python object.  The check must not have any side effects.  Otherwise the
    code is being asked to convert the Python object and a non-zero value
    should be returned through this pointer if an error occurred during the
    conversion.

PyObject \*sipPy
    This is the Python object to be converted.

*type* \*\*sipCppPtr
    This is a pointer through which the address of the mapped type instance (or
    zero if appropriate) is returned.  Its value is undefined if ``sipIsErr``
    is ``NULL``.

PyObject \*sipTransferObj
    This specifies any desired ownership changes to *sipPy*.  If it is ``NULL``
    then the ownership should be left unchanged.  If it is ``Py_None`` then
    ownership should be transferred to Python.  Otherwise ownership should be
    transferred to C/C++ and *sipPy* associated with *sipTransferObj*.  The
    code can choose to interpret these changes in any way.

The handwritten code must explicitly return an ``int`` the meaning of which
depends on the value of ``sipIsErr``.

If ``sipIsErr`` is ``NULL`` then a non-zero value is returned if the Python
object has a type that can be converted to the mapped type.  Otherwise zero is
returned.

If ``sipIsErr`` is not ``NULL`` then a combination of the following flags is
returned.

        - ``SIP_TEMPORARY`` is set to indicate that the returned instance is a
          temporary and should be released to avoid a memory leak.

        - ``SIP_DERIVED_CLASS`` is set to indicate that the type of the
          returned instance is a derived class.  See `Generated Derived
          Classes`_.

The following example converts a Python list of ``QPoint`` instances to a
``QList<QPoint>`` instance::

    %ConvertToTypeCode
        // See if we are just being asked to check the type of the Python
        // object.
        if (!sipIsErr)
        {
            // Checking whether or not None has been passed instead of a list
            // has already been done.
            if (!PyList_Check(sipPy))
                return 0;

            // Check the type of each element.  We specify SIP_NOT_NONE to
            // disallow None because it is a list of QPoint, not of a pointer
            // to a QPoint, so None isn't appropriate.
            for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
                if (!sipCanConvertToInstance(PyList_GET_ITEM(sipPy, i),
                                             sipClass_QPoint, SIP_NOT_NONE))
                    return 0;

            // The type is valid.
            return 1;
        }

        // Create the instance on the heap.
        QList<QPoint> *ql = new QList<QPoint>;

        for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
        {
            QPoint *qp;
            int state;

            // Get the address of the element's C++ instance.  Note that, in
            // this case, we don't apply any ownership changes to the list
            // elements, only to the list itself.
            qp = reinterpret_cast<QPoint *>(sipConvertToInstance(
                                                    PyList_GET_ITEM(sipPy, i),
                                                    sipClass_QPoint, 0,
                                                    SIP_NOT_NONE,
                                                    &state, sipIsErr));

            // Deal with any errors.
            if (*sipIsErr)
            {
                sipReleaseInstance(qp, sipClass_QPoint, state);

                // Tidy up.
                delete ql;

                // There is no temporary instance.
                return 0;
            }

            ql -> append(*qp);

            // A copy of the QPoint was appended to the list so we no longer
            // need it.  It may be a temporary instance that should be
            // destroyed, or a wrapped instance that should not be destroyed.
            // sipReleaseInstance() will do the right thing.
            sipReleaseInstance(qp, sipClass_QPoint, state);
        }

        // Return the instance.
        *sipCppPtr = ql;

        // The instance should be regarded as temporary (and be destroyed as
        // soon as it has been used) unless it has been transferred from
        // Python.  sipGetState() is a convenience function that implements
        // this common transfer behaviour.
        return sipGetState(sipTransferObj);
    %End

When used in a class specification the handwritten code replaces the code that
would normally be automatically generated.  This means that the handwritten
code must also handle instances of the class itself and not just the additional
types that are being supported.  This should be done by making calls to
`sipCanConvertToInstance()`_ to check the object type and
`sipConvertToInstance()`_ to convert the object.  The ``SIP_NO_CONVERTORS``
flag *must* be passed to both these functions to prevent recursive calls to the
handwritten code.


%Copying
--------

.. parsed-literal::

    %Copying
        *text*
    %End

This directive is used to specify some arbitrary text that will be included at
the start of all source files generated by SIP.  It is normally used to
include copyright and licensing terms.

For example::

    %Copying
    Copyright (c) 2006 Riverbank Computing Limited
    %End


%Doc
----

.. parsed-literal::

    %Doc
        *text*
    %End

This directive is used to specify some arbitrary text that will be extracted
by SIP when the ``-d`` command line option is used.  The directive can be
specified any number of times and SIP will concatenate all the separate pieces
of text in the order that it sees them.

Documentation that is specified using this directive is local to the module in
which it appears.  It is ignored by modules that `%Import`_ it.  Use the
`%ExportedDoc`_ directive for documentation that should be included by all
modules that `%Import`_ this one.

For example::

    %Doc
    <h1>An Example</h1>
    <p>
    This fragment of documentation is HTML and is local to the module in
    which it is defined