Simple types
++++++++++++

Simple types have some special behaviour: When they are accessed as
structure or union fields, items of array instances, or as foreign
function return values, they are transparently converted from and to
the native Python types int, long, string, and unicode.

This is *not* the case for subclasses of simple data types, so while a
``c_void_p`` type is transparently converted from and to Python
integer or long, a subclass of c_void_p is *not* converted.  This
allows you to define new behaviour almost completely.

Class attributes of simple types
--------------------------------

``__ctype_be__``, ``__ctype_le__``

    If the type supports different byte order (pointer types do NOT
    support this), ``__ctype_be__`` and ``__ctype_le__`` are types
    with bug endian and little endian byte order.  For example,
    ``c_int.__ctype_be__`` is an integer type with the memory block in
    big endian byte order.

``_type_``

    Implementation artifact: the typecode for this type, a single
    character string code compatible to what the ``struct`` module uses.
    Additional characters are used for types that the ``struct`` module
    does not support.


Class methods of simple types
-----------------------------

(To be exact, these are not class methods, instead these are methods
of the metaclass.  The most prominent difference to classmethods is
that you can call these methods on the class, but not on the instance
of the simple type.)

``__ctypes_from_outparam__``

    TBD

``from_address``

    TBD

``from_param``

    This class method is used to adapt function parameters.  If a type
    is specified in a function's argtypes sequence, in a function call
    the ``from_param(arg)`` method will be called with the actual
    argument, and the result will be passed to the foreign function
    call as a parameter.

    ``from_param`` usually returns an internal object that you cannot
    use in Python code - it only makes sense to pass this object to
    foreign functions.

    On one hand, ``from_param`` is a performance optimization - it
    allows you to pass Python integers to function calls expecting a
    ``c_int`` argument type, without having to create a full-featured
    ``c_int`` instance.

    On the other hand, ``from_param`` can adapt other objects to
    parameters.  XXX explain the automatic ``byref`` call for byref
    arguments.

``in_dll``

    TBD

Instance attributes of simple types
-----------------------------------

``value``

    Allows to get or set the current value of the object.  For simple
    types, this is always a native Python object like integer, long,
    string, unicode, or None.

``_objects`` (never modify this)

    Implementation artifact: a Python object keeping references to
    other objects which must be kept alive.  Never modify anything on
    the returned object. XXX Should probably not be exposed.

``_b_base_`` (readonly)

    Implementation artifact: the base object owning the memory block
    (if any).

``_b_needsfree_`` (readonly)

    Implementation artifact: does this object have to free its memory
    block on destruction.

``_as_parameter_`` (readonly)

    Implementation artifact (?): how to pass this object as a function
    parameter.


Numeric types
-------------

Integer types are ``c_byte``, ``c_short``, ``c_int``, ``c_long``,
``c_longlong`` and their unsigned variants ``c_ubyte``, ``c_ushort``,
``c_uint``, ``c_ulong`` and ``c_ulonglong``, floating point types are
``c_float`` and ``c_double``.

The constructor and the ``from_param`` class method accept a Python
integer for integer types, a Python float for floating point types.

On 32-bit platforms where sizeof(int) == sizeof(long), ``c_int`` is an
alias for ``c_long``, on 64-bit platforms where sizeof(long) ==
sizeof(long long), ``c_long`` is an alias for ``c_longlong``.

Character types
---------------

Character types are ``c_char`` and ``c_wchar``, representing the C
``char`` and ``wchar_t`` types.

The constructor and the ``from_param`` class method accept a single
character Python string or unicode string.  Conversion between string
and unicode, if needed, is done according to the ctypes
encoding/decoding rules.


Pointer types
-------------

The only simple pointer type is ``c_void_p``, which represents the C
``void *`` data type.  ``c_void_p`` can also be written as
``POINTER(None)``.

The constructor accepts one optional argument, which must be an
integer or long (interpreted as an address), or ``None``.

The ``from_param`` class method accepts everything that could be used
as a pointer.  XXX Should accept objects using the buffer interface as
well.

The ``value`` attribute accepts and returns None or integer.

XXX Shouldn't the constructor accept the same types as from_param?


String types
------------

ctypes has the ``c_char_p`` and ``c_wchar_p`` types which represent
const pointers to zero terminated strings in C: ``const char *`` and
``const wchar_t *``.  Since strings and Unicode instances are
immutable, these types should be considered readonly: do not pass them
to functions that write into the buffer.

The constructor accepts one optional argument, which must be a Python
or unicode string, an integer, or ``None``.

The ``from_param`` class method accepts a string or a Unicode string,
as well as ``None``.  Conversion between string and Unicode, if
needed, is done according to the ctypes encoding/decoding rules.

XXX Why does the constructor accept an integer, and from_param doesn't?