CType types and instances

  "ctypes home":../ctypes.html :: "tutorial":tutorial.html :: reference :: "faq":faq.html

  Common operations on CType instances

    'sizeof(obj) -> integer'

        Return an integer specifying the number of bytes in the memory
        block.  This corresponds to the C code 'sizeof(obj)'.  Does
        also work for types.

    'byref(obj) -> magic'

        Similar to '&obj' in C code, but only usable while passing the
        object as a parameter to a C function call.  Internally this
        calls 'obj._as_ref_', see below.

    'pointer(obj) -> CType instance'

        Same as '&obj' in C.  Different from 'byref(obj)', this
        creates a new CType object, acting as a pointer to 'obj'.  It
        will be an instance of a pointer class pointing to 'type(obj)'
        instances.  The pointer class is created on the fly, if it
        does not yet exist.

  Common operation on CType types

    CType types/classes extensively use the new Python type system, so
    the following may first look unusual to the Pyhon programmer.

    'POINTER(type) -> class'

        Return a subclass of 'CType', which is a pointer to 'type'.
        The subclass will be created if it does not yet exist,
        otherwise it is returned from a buildin cache.

    'type * num -> array class'

        Multiplying a CType class with a positive integer creates a
        subclass of 'CType', which is an array type holding 'num'
        instances of 'type'.

    'type.from_address(address) -> CType instance'

        Create a new instance of 'type' from the memory block at the
        integer 'address'.

<!--
  Internal CType class methods/properties

    'type._from_python_(value) -> magic'

        Convert a python object 'value' into something that can be
        used as a parameter in a C function call.  This may be a 'type'
        instance, or something else.  Automatically called when you
        have specified 'type' in the function call prototype.  If
        'value' is not compatible with 'type', a 'TypeError' will be
        raised.

    'type._from_c_(xxx) -> Python object'

        Convert a C data object into a Python object. Called
        internally when a callback function is called, and you have
        specified 'type' as an argument.  The result may or may not be
        an instance of 'type'.
-->

  Internal CType methods/properties

    'obj._as_parameter_ -> magic'

        Automatically called when a CType object is used as a
        parameter in a C function call *by value*.  Must *return*
        something that can be understood by the C function call
        parameter converter.  Currently, it either returns an integer,
        a string or a unicode string, or a 2-tuple or 3-tuple of the
        form '(typecode, value[, ref])'.

	If an integer, a string, or a unicode string is returned, they
	are passed directly to the API call as 'int' or 'char *' or 'wchar_t *'.

	If a tuple 'typecode' is a single letter string containing a
	format code like the standard 'array' module uses.  'value' is
	a Python character, integer, long, or float.  'ref' can be used
	to keep the original object alive until the C function call
	returns, it is optional.

<!--
    'obj._as_ref_ -> magic'

    	Convert the object to something that can be used as a
	parameter to a C function call *by reference*.  The same
	conventions as in '_as_parameter_' are used, except that the
	meaning of the result is the address, not the value.
-->