| \ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi |
| \setlength{\locallinewidth}{\linewidth} |
| \section{\module{ctypes} --- A foreign function library for Python.} |
| \declaremodule{standard}{ctypes} |
| \moduleauthor{Thomas Heller}{theller@python.net} |
| \modulesynopsis{A foreign function library for Python.} |
| \versionadded{2.5} |
| |
| \code{ctypes} is a foreign function library for Python. It provides C |
| compatible data types, and allows to call functions in dlls/shared |
| libraries. It can be used to wrap these libraries in pure Python. |
| |
| |
| \subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}} |
| |
| Note: The code samples in this tutorial uses \code{doctest} to make sure |
| that they actually work. Since some code samples behave differently |
| under Linux, Windows, or Mac OS X, they contain doctest directives in |
| comments. |
| |
| Note: Quite some code samples references the ctypes \class{c{\_}int} type. |
| This type is an alias to the \class{c{\_}long} type on 32-bit systems. So, |
| you should not be confused if \class{c{\_}long} is printed if you would |
| expect \class{c{\_}int} - they are actually the same type. |
| |
| |
| \subsubsection{Loading dynamic link libraries\label{ctypes-loading-dynamic-link-libraries}} |
| |
| \code{ctypes} exports the \var{cdll}, and on Windows also \var{windll} and |
| \var{oledll} objects to load dynamic link libraries. |
| |
| You load libraries by accessing them as attributes of these objects. |
| \var{cdll} loads libraries which export functions using the standard |
| \code{cdecl} calling convention, while \var{windll} libraries call |
| functions using the \code{stdcall} calling convention. \var{oledll} also |
| uses the \code{stdcall} calling convention, and assumes the functions |
| return a Windows \class{HRESULT} error code. The error code is used to |
| automatically raise \class{WindowsError} Python exceptions when the |
| function call fails. |
| |
| Here are some examples for Windows, note that \code{msvcrt} is the MS |
| standard C library containing most standard C functions, and uses the |
| cdecl calling convention: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> print windll.kernel32 # doctest: +WINDOWS |
| <WinDLL 'kernel32', handle ... at ...> |
| >>> print cdll.msvcrt # doctest: +WINDOWS |
| <CDLL 'msvcrt', handle ... at ...> |
| >>> libc = cdll.msvcrt # doctest: +WINDOWS |
| >>> |
| \end{verbatim} |
| |
| Windows appends the usual '.dll' file suffix automatically. |
| |
| On Linux, it is required to specify the filename \emph{including} the |
| extension to load a library, so attribute access does not work. |
| Either the \method{LoadLibrary} method of the dll loaders should be used, |
| or you should load the library by creating an instance of CDLL by |
| calling the constructor: |
| \begin{verbatim} |
| >>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX |
| <CDLL 'libc.so.6', handle ... at ...> |
| >>> libc = CDLL("libc.so.6") # doctest: +LINUX |
| >>> libc # doctest: +LINUX |
| <CDLL 'libc.so.6', handle ... at ...> |
| >>> |
| \end{verbatim} |
| % XXX Add section for Mac OS X. |
| |
| |
| \subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}} |
| |
| Functions are accessed as attributes of dll objects: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> libc.printf |
| <_FuncPtr object at 0x...> |
| >>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS |
| <_FuncPtr object at 0x...> |
| >>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "ctypes.py", line 239, in __getattr__ |
| func = _StdcallFuncPtr(name, self) |
| AttributeError: function 'MyOwnFunction' not found |
| >>> |
| \end{verbatim} |
| |
| Note that win32 system dlls like \code{kernel32} and \code{user32} often |
| export ANSI as well as UNICODE versions of a function. The UNICODE |
| version is exported with an \code{W} appended to the name, while the ANSI |
| version is exported with an \code{A} appended to the name. The win32 |
| \code{GetModuleHandle} function, which returns a \emph{module handle} for a |
| given module name, has the following C prototype, and a macro is used |
| to expose one of them as \code{GetModuleHandle} depending on whether |
| UNICODE is defined or not: |
| \begin{verbatim} |
| /* ANSI version */ |
| HMODULE GetModuleHandleA(LPCSTR lpModuleName); |
| /* UNICODE version */ |
| HMODULE GetModuleHandleW(LPCWSTR lpModuleName); |
| \end{verbatim} |
| |
| \var{windll} does not try to select one of them by magic, you must |
| access the version you need by specifying \code{GetModuleHandleA} or |
| \code{GetModuleHandleW} explicitely, and then call it with normal strings |
| or unicode strings respectively. |
| |
| Sometimes, dlls export functions with names which aren't valid Python |
| identifiers, like \code{"??2@YAPAXI@Z"}. In this case you have to use |
| \code{getattr} to retrieve the function: |
| \begin{verbatim} |
| >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS |
| <_FuncPtr object at 0x...> |
| >>> |
| \end{verbatim} |
| |
| On Windows, some dlls export functions not by name but by ordinal. |
| These functions can be accessed by indexing the dll object with the |
| ordinal number: |
| \begin{verbatim} |
| >>> cdll.kernel32[1] # doctest: +WINDOWS |
| <_FuncPtr object at 0x...> |
| >>> cdll.kernel32[0] # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "ctypes.py", line 310, in __getitem__ |
| func = _StdcallFuncPtr(name, self) |
| AttributeError: function ordinal 0 not found |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Calling functions\label{ctypes-calling-functions}} |
| |
| You can call these functions like any other Python callable. This |
| example uses the \code{time()} function, which returns system time in |
| seconds since the \UNIX{} epoch, and the \code{GetModuleHandleA()} function, |
| which returns a win32 module handle. |
| |
| This example calls both functions with a NULL pointer (\code{None} should |
| be used as the NULL pointer): |
| \begin{verbatim} |
| >>> print libc.time(None) # doctest: +SKIP |
| 1150640792 |
| >>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS |
| 0x1d000000 |
| >>> |
| \end{verbatim} |
| |
| \code{ctypes} tries to protect you from calling functions with the wrong |
| number of arguments or the wrong calling convention. Unfortunately |
| this only works on Windows. It does this by examining the stack after |
| the function returns, so although an error is raised the function |
| \emph{has} been called: |
| \begin{verbatim} |
| >>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: Procedure probably called with not enough arguments (4 bytes missing) |
| >>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: Procedure probably called with too many arguments (4 bytes in excess) |
| >>> |
| \end{verbatim} |
| |
| The same exception is raised when you call an \code{stdcall} function |
| with the \code{cdecl} calling convention, or vice versa: |
| \begin{verbatim} |
| >>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: Procedure probably called with not enough arguments (4 bytes missing) |
| >>> |
| |
| >>> windll.msvcrt.printf("spam") # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: Procedure probably called with too many arguments (4 bytes in excess) |
| >>> |
| \end{verbatim} |
| |
| To find out the correct calling convention you have to look into the C |
| header file or the documentation for the function you want to call. |
| |
| On Windows, \code{ctypes} uses win32 structured exception handling to |
| prevent crashes from general protection faults when functions are |
| called with invalid argument values: |
| \begin{verbatim} |
| >>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| WindowsError: exception: access violation reading 0x00000020 |
| >>> |
| \end{verbatim} |
| |
| There are, however, enough ways to crash Python with \code{ctypes}, so |
| you should be careful anyway. |
| |
| \code{None}, integers, longs, byte strings and unicode strings are the |
| only native Python objects that can directly be used as parameters in |
| these function calls. \code{None} is passed as a C \code{NULL} pointer, |
| byte strings and unicode strings are passed as pointer to the memory |
| block that contains their data (\code{char *} or \code{wchar{\_}t *}). Python |
| integers and Python longs are passed as the platforms default C |
| \code{int} type, their value is masked to fit into the C type. |
| |
| Before we move on calling functions with other parameter types, we |
| have to learn more about \code{ctypes} data types. |
| |
| |
| \subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}} |
| |
| \code{ctypes} defines a number of primitive C compatible data types : |
| \begin{quote} |
| \begin{tableiii}{l|l|l}{textrm} |
| { |
| ctypes type |
| } |
| { |
| C type |
| } |
| { |
| Python type |
| } |
| \lineiii{ |
| \class{c{\_}char} |
| } |
| { |
| \code{char} |
| } |
| { |
| 1-character |
| string |
| } |
| \lineiii{ |
| \class{c{\_}wchar} |
| } |
| { |
| \code{wchar{\_}t} |
| } |
| { |
| 1-character |
| unicode string |
| } |
| \lineiii{ |
| \class{c{\_}byte} |
| } |
| { |
| \code{char} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}ubyte} |
| } |
| { |
| \code{unsigned char} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}short} |
| } |
| { |
| \code{short} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}ushort} |
| } |
| { |
| \code{unsigned short} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}int} |
| } |
| { |
| \code{int} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}uint} |
| } |
| { |
| \code{unsigned int} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}long} |
| } |
| { |
| \code{long} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}ulong} |
| } |
| { |
| \code{unsigned long} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}longlong} |
| } |
| { |
| \code{{\_}{\_}int64} or |
| \code{long long} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}ulonglong} |
| } |
| { |
| \code{unsigned {\_}{\_}int64} or |
| \code{unsigned long long} |
| } |
| { |
| int/long |
| } |
| \lineiii{ |
| \class{c{\_}float} |
| } |
| { |
| \code{float} |
| } |
| { |
| float |
| } |
| \lineiii{ |
| \class{c{\_}double} |
| } |
| { |
| \code{double} |
| } |
| { |
| float |
| } |
| \lineiii{ |
| \class{c{\_}char{\_}p} |
| } |
| { |
| \code{char *} |
| (NUL terminated) |
| } |
| { |
| string or |
| \code{None} |
| } |
| \lineiii{ |
| \class{c{\_}wchar{\_}p} |
| } |
| { |
| \code{wchar{\_}t *} |
| (NUL terminated) |
| } |
| { |
| unicode or |
| \code{None} |
| } |
| \lineiii{ |
| \class{c{\_}void{\_}p} |
| } |
| { |
| \code{void *} |
| } |
| { |
| int/long |
| or \code{None} |
| } |
| \end{tableiii} |
| \end{quote} |
| |
| All these types can be created by calling them with an optional |
| initializer of the correct type and value: |
| \begin{verbatim} |
| >>> c_int() |
| c_long(0) |
| >>> c_char_p("Hello, World") |
| c_char_p('Hello, World') |
| >>> c_ushort(-3) |
| c_ushort(65533) |
| >>> |
| \end{verbatim} |
| |
| Since these types are mutable, their value can also be changed |
| afterwards: |
| \begin{verbatim} |
| >>> i = c_int(42) |
| >>> print i |
| c_long(42) |
| >>> print i.value |
| 42 |
| >>> i.value = -99 |
| >>> print i.value |
| -99 |
| >>> |
| \end{verbatim} |
| |
| Assigning a new value to instances of the pointer types \class{c{\_}char{\_}p}, |
| \class{c{\_}wchar{\_}p}, and \class{c{\_}void{\_}p} changes the \emph{memory location} they |
| point to, \emph{not the contents} of the memory block (of course not, |
| because Python strings are immutable): |
| \begin{verbatim} |
| >>> s = "Hello, World" |
| >>> c_s = c_char_p(s) |
| >>> print c_s |
| c_char_p('Hello, World') |
| >>> c_s.value = "Hi, there" |
| >>> print c_s |
| c_char_p('Hi, there') |
| >>> print s # first string is unchanged |
| Hello, World |
| >>> |
| \end{verbatim} |
| |
| You should be careful, however, not to pass them to functions |
| expecting pointers to mutable memory. If you need mutable memory |
| blocks, ctypes has a \code{create{\_}string{\_}buffer} function which creates |
| these in various ways. The current memory block contents can be |
| accessed (or changed) with the \code{raw} property, if you want to access |
| it as NUL terminated string, use the \code{string} property: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes |
| >>> print sizeof(p), repr(p.raw) |
| 3 '\x00\x00\x00' |
| >>> p = create_string_buffer("Hello") # create a buffer containing a NUL terminated string |
| >>> print sizeof(p), repr(p.raw) |
| 6 'Hello\x00' |
| >>> print repr(p.value) |
| 'Hello' |
| >>> p = create_string_buffer("Hello", 10) # create a 10 byte buffer |
| >>> print sizeof(p), repr(p.raw) |
| 10 'Hello\x00\x00\x00\x00\x00' |
| >>> p.value = "Hi" |
| >>> print sizeof(p), repr(p.raw) |
| 10 'Hi\x00lo\x00\x00\x00\x00\x00' |
| >>> |
| \end{verbatim} |
| |
| The \code{create{\_}string{\_}buffer} function replaces the \code{c{\_}buffer} |
| function (which is still available as an alias), as well as the |
| \code{c{\_}string} function from earlier ctypes releases. To create a |
| mutable memory block containing unicode characters of the C type |
| \code{wchar{\_}t} use the \code{create{\_}unicode{\_}buffer} function. |
| |
| |
| \subsubsection{Calling functions, continued\label{ctypes-calling-functions-continued}} |
| |
| Note that printf prints to the real standard output channel, \emph{not} to |
| \code{sys.stdout}, so these examples will only work at the console |
| prompt, not from within \emph{IDLE} or \emph{PythonWin}: |
| \begin{verbatim} |
| >>> printf = libc.printf |
| >>> printf("Hello, %s\n", "World!") |
| Hello, World! |
| 14 |
| >>> printf("Hello, %S", u"World!") |
| Hello, World! |
| 13 |
| >>> printf("%d bottles of beer\n", 42) |
| 42 bottles of beer |
| 19 |
| >>> printf("%f bottles of beer\n", 42.5) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2 |
| >>> |
| \end{verbatim} |
| |
| As has been mentioned before, all Python types except integers, |
| strings, and unicode strings have to be wrapped in their corresponding |
| \code{ctypes} type, so that they can be converted to the required C data |
| type: |
| \begin{verbatim} |
| >>> printf("An int %d, a double %f\n", 1234, c_double(3.14)) |
| Integer 1234, double 3.1400001049 |
| 31 |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Calling functions with your own custom data types\label{ctypes-calling-functions-with-own-custom-data-types}} |
| |
| You can also customize \code{ctypes} argument conversion to allow |
| instances of your own classes be used as function arguments. |
| \code{ctypes} looks for an \member{{\_}as{\_}parameter{\_}} attribute and uses this as |
| the function argument. Of course, it must be one of integer, string, |
| or unicode: |
| \begin{verbatim} |
| >>> class Bottles(object): |
| ... def __init__(self, number): |
| ... self._as_parameter_ = number |
| ... |
| >>> bottles = Bottles(42) |
| >>> printf("%d bottles of beer\n", bottles) |
| 42 bottles of beer |
| 19 |
| >>> |
| \end{verbatim} |
| |
| If you don't want to store the instance's data in the |
| \member{{\_}as{\_}parameter{\_}} instance variable, you could define a \code{property} |
| which makes the data avaiblable. |
| |
| |
| \subsubsection{Specifying the required argument types (function prototypes)\label{ctypes-specifying-required-argument-types}} |
| |
| It is possible to specify the required argument types of functions |
| exported from DLLs by setting the \member{argtypes} attribute. |
| |
| \member{argtypes} must be a sequence of C data types (the \code{printf} |
| function is probably not a good example here, because it takes a |
| variable number and different types of parameters depending on the |
| format string, on the other hand this is quite handy to experiment |
| with this feature): |
| \begin{verbatim} |
| >>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double] |
| >>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2) |
| String 'Hi', Int 10, Double 2.200000 |
| 37 |
| >>> |
| \end{verbatim} |
| |
| Specifying a format protects against incompatible argument types (just |
| as a prototype for a C function), and tries to convert the arguments |
| to valid types: |
| \begin{verbatim} |
| >>> printf("%d %d %d", 1, 2, 3) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ArgumentError: argument 2: exceptions.TypeError: wrong type |
| >>> printf("%s %d %f", "X", 2, 3) |
| X 2 3.00000012 |
| 12 |
| >>> |
| \end{verbatim} |
| |
| If you have defined your own classes which you pass to function calls, |
| you have to implement a \method{from{\_}param} class method for them to be |
| able to use them in the \member{argtypes} sequence. The \method{from{\_}param} |
| class method receives the Python object passed to the function call, |
| it should do a typecheck or whatever is needed to make sure this |
| object is acceptable, and then return the object itself, it's |
| \member{{\_}as{\_}parameter{\_}} attribute, or whatever you want to pass as the C |
| function argument in this case. Again, the result should be an |
| integer, string, unicode, a \code{ctypes} instance, or something having |
| the \member{{\_}as{\_}parameter{\_}} attribute. |
| |
| |
| \subsubsection{Return types\label{ctypes-return-types}} |
| |
| By default functions are assumed to return the C \code{int} type. Other |
| return types can be specified by setting the \member{restype} attribute of |
| the function object. |
| |
| Here is a more advanced example, it uses the \code{strchr} function, which |
| expects a string pointer and a char, and returns a pointer to a |
| string: |
| \begin{verbatim} |
| >>> strchr = libc.strchr |
| >>> strchr("abcdef", ord("d")) # doctest: +SKIP |
| 8059983 |
| >>> strchr.restype = c_char_p # c_char_p is a pointer to a string |
| >>> strchr("abcdef", ord("d")) |
| 'def' |
| >>> print strchr("abcdef", ord("x")) |
| None |
| >>> |
| \end{verbatim} |
| |
| If you want to avoid the \code{ord("x")} calls above, you can set the |
| \member{argtypes} attribute, and the second argument will be converted from |
| a single character Python string into a C char: |
| \begin{verbatim} |
| >>> strchr.restype = c_char_p |
| >>> strchr.argtypes = [c_char_p, c_char] |
| >>> strchr("abcdef", "d") |
| 'def' |
| >>> strchr("abcdef", "def") |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ArgumentError: argument 2: exceptions.TypeError: one character string expected |
| >>> print strchr("abcdef", "x") |
| None |
| >>> strchr("abcdef", "d") |
| 'def' |
| >>> |
| \end{verbatim} |
| |
| You can also use a callable Python object (a function or a class for |
| example) as the \member{restype} attribute, if the foreign function returns |
| an integer. The callable will be called with the \code{integer} the C |
| function returns, and the result of this call will be used as the |
| result of your function call. This is useful to check for error return |
| values and automatically raise an exception: |
| \begin{verbatim} |
| >>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS |
| >>> def ValidHandle(value): |
| ... if value == 0: |
| ... raise WinError() |
| ... return value |
| ... |
| >>> |
| >>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS |
| >>> GetModuleHandle(None) # doctest: +WINDOWS |
| 486539264 |
| >>> GetModuleHandle("something silly") # doctest: +WINDOWS |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "<stdin>", line 3, in ValidHandle |
| WindowsError: [Errno 126] The specified module could not be found. |
| >>> |
| \end{verbatim} |
| |
| \code{WinError} is a function which will call Windows \code{FormatMessage()} |
| api to get the string representation of an error code, and \emph{returns} |
| an exception. \code{WinError} takes an optional error code parameter, if |
| no one is used, it calls \function{GetLastError()} to retrieve it. |
| |
| Please note that a much more powerful error checking mechanism is |
| available through the \member{errcheck} attribute; see the reference manual |
| for details. |
| |
| |
| \subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}} |
| |
| Sometimes a C api function expects a \emph{pointer} to a data type as |
| parameter, probably to write into the corresponding location, or if |
| the data is too large to be passed by value. This is also known as |
| \emph{passing parameters by reference}. |
| |
| \code{ctypes} exports the \function{byref} function which is used to pass |
| parameters by reference. The same effect can be achieved with the |
| \code{pointer} function, although \code{pointer} does a lot more work since |
| it constructs a real pointer object, so it is faster to use \function{byref} |
| if you don't need the pointer object in Python itself: |
| \begin{verbatim} |
| >>> i = c_int() |
| >>> f = c_float() |
| >>> s = create_string_buffer('\000' * 32) |
| >>> print i.value, f.value, repr(s.value) |
| 0 0.0 '' |
| >>> libc.sscanf("1 3.14 Hello", "%d %f %s", |
| ... byref(i), byref(f), s) |
| 3 |
| >>> print i.value, f.value, repr(s.value) |
| 1 3.1400001049 'Hello' |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Structures and unions\label{ctypes-structures-unions}} |
| |
| Structures and unions must derive from the \class{Structure} and \class{Union} |
| base classes which are defined in the \code{ctypes} module. Each subclass |
| must define a \member{{\_}fields{\_}} attribute. \member{{\_}fields{\_}} must be a list of |
| \emph{2-tuples}, containing a \emph{field name} and a \emph{field type}. |
| |
| The field type must be a \code{ctypes} type like \class{c{\_}int}, or any other |
| derived \code{ctypes} type: structure, union, array, pointer. |
| |
| Here is a simple example of a POINT structure, which contains two |
| integers named \code{x} and \code{y}, and also shows how to initialize a |
| structure in the constructor: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> class POINT(Structure): |
| ... _fields_ = [("x", c_int), |
| ... ("y", c_int)] |
| ... |
| >>> point = POINT(10, 20) |
| >>> print point.x, point.y |
| 10 20 |
| >>> point = POINT(y=5) |
| >>> print point.x, point.y |
| 0 5 |
| >>> POINT(1, 2, 3) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| ValueError: too many initializers |
| >>> |
| \end{verbatim} |
| |
| You can, however, build much more complicated structures. Structures |
| can itself contain other structures by using a structure as a field |
| type. |
| |
| Here is a RECT structure which contains two POINTs named \code{upperleft} |
| and \code{lowerright} |
| \begin{verbatim} |
| >>> class RECT(Structure): |
| ... _fields_ = [("upperleft", POINT), |
| ... ("lowerright", POINT)] |
| ... |
| >>> rc = RECT(point) |
| >>> print rc.upperleft.x, rc.upperleft.y |
| 0 5 |
| >>> print rc.lowerright.x, rc.lowerright.y |
| 0 0 |
| >>> |
| \end{verbatim} |
| |
| Nested structures can also be initialized in the constructor in |
| several ways: |
| \begin{verbatim} |
| >>> r = RECT(POINT(1, 2), POINT(3, 4)) |
| >>> r = RECT((1, 2), (3, 4)) |
| \end{verbatim} |
| |
| Fields descriptors can be retrieved from the \emph{class}, they are useful |
| for debugging because they can provide useful information: |
| \begin{verbatim} |
| >>> print POINT.x |
| <Field type=c_long, ofs=0, size=4> |
| >>> print POINT.y |
| <Field type=c_long, ofs=4, size=4> |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Structure/union alignment and byte order\label{ctypes-structureunion-alignment-byte-order}} |
| |
| By default, Structure and Union fields are aligned in the same way the |
| C compiler does it. It is possible to override this behaviour be |
| specifying a \member{{\_}pack{\_}} class attribute in the subclass |
| definition. This must be set to a positive integer and specifies the |
| maximum alignment for the fields. This is what \code{{\#}pragma pack(n)} |
| also does in MSVC. |
| |
| \code{ctypes} uses the native byte order for Structures and Unions. To |
| build structures with non-native byte order, you can use one of the |
| BigEndianStructure, LittleEndianStructure, BigEndianUnion, and |
| LittleEndianUnion base classes. These classes cannot contain pointer |
| fields. |
| |
| |
| \subsubsection{Bit fields in structures and unions\label{ctypes-bit-fields-in-structures-unions}} |
| |
| It is possible to create structures and unions containing bit fields. |
| Bit fields are only possible for integer fields, the bit width is |
| specified as the third item in the \member{{\_}fields{\_}} tuples: |
| \begin{verbatim} |
| >>> class Int(Structure): |
| ... _fields_ = [("first_16", c_int, 16), |
| ... ("second_16", c_int, 16)] |
| ... |
| >>> print Int.first_16 |
| <Field type=c_long, ofs=0:0, bits=16> |
| >>> print Int.second_16 |
| <Field type=c_long, ofs=0:16, bits=16> |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Arrays\label{ctypes-arrays}} |
| |
| Arrays are sequences, containing a fixed number of instances of the |
| same type. |
| |
| The recommended way to create array types is by multiplying a data |
| type with a positive integer: |
| \begin{verbatim} |
| TenPointsArrayType = POINT * 10 |
| \end{verbatim} |
| |
| Here is an example of an somewhat artifical data type, a structure |
| containing 4 POINTs among other stuff: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> class POINT(Structure): |
| ... _fields_ = ("x", c_int), ("y", c_int) |
| ... |
| >>> class MyStruct(Structure): |
| ... _fields_ = [("a", c_int), |
| ... ("b", c_float), |
| ... ("point_array", POINT * 4)] |
| >>> |
| >>> print len(MyStruct().point_array) |
| 4 |
| >>> |
| \end{verbatim} |
| |
| Instances are created in the usual way, by calling the class: |
| \begin{verbatim} |
| arr = TenPointsArrayType() |
| for pt in arr: |
| print pt.x, pt.y |
| \end{verbatim} |
| |
| The above code print a series of \code{0 0} lines, because the array |
| contents is initialized to zeros. |
| |
| Initializers of the correct type can also be specified: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> TenIntegers = c_int * 10 |
| >>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) |
| >>> print ii |
| <c_long_Array_10 object at 0x...> |
| >>> for i in ii: print i, |
| ... |
| 1 2 3 4 5 6 7 8 9 10 |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Pointers\label{ctypes-pointers}} |
| |
| Pointer instances are created by calling the \code{pointer} function on a |
| \code{ctypes} type: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> i = c_int(42) |
| >>> pi = pointer(i) |
| >>> |
| \end{verbatim} |
| |
| Pointer instances have a \code{contents} attribute which returns the |
| object to which the pointer points, the \code{i} object above: |
| \begin{verbatim} |
| >>> pi.contents |
| c_long(42) |
| >>> |
| \end{verbatim} |
| |
| Note that \code{ctypes} does not have OOR (original object return), it |
| constructs a new, equivalent object each time you retrieve an |
| attribute: |
| \begin{verbatim} |
| >>> pi.contents is i |
| False |
| >>> pi.contents is pi.contents |
| False |
| >>> |
| \end{verbatim} |
| |
| Assigning another \class{c{\_}int} instance to the pointer's contents |
| attribute would cause the pointer to point to the memory location |
| where this is stored: |
| \begin{verbatim} |
| >>> i = c_int(99) |
| >>> pi.contents = i |
| >>> pi.contents |
| c_long(99) |
| >>> |
| \end{verbatim} |
| |
| Pointer instances can also be indexed with integers: |
| \begin{verbatim} |
| >>> pi[0] |
| 99 |
| >>> |
| \end{verbatim} |
| |
| Assigning to an integer index changes the pointed to value: |
| \begin{verbatim} |
| >>> print i |
| c_long(99) |
| >>> pi[0] = 22 |
| >>> print i |
| c_long(22) |
| >>> |
| \end{verbatim} |
| |
| It is also possible to use indexes different from 0, but you must know |
| what you're doing, just as in C: You can access or change arbitrary |
| memory locations. Generally you only use this feature if you receive a |
| pointer from a C function, and you \emph{know} that the pointer actually |
| points to an array instead of a single item. |
| |
| Behind the scenes, the \code{pointer} function does more than simply |
| create pointer instances, it has to create pointer \emph{types} first. |
| This is done with the \code{POINTER} function, which accepts any |
| \code{ctypes} type, and returns a new type: |
| \begin{verbatim} |
| >>> PI = POINTER(c_int) |
| >>> PI |
| <class 'ctypes.LP_c_long'> |
| >>> PI(42) |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: expected c_long instead of int |
| >>> PI(c_int(42)) |
| <ctypes.LP_c_long object at 0x...> |
| >>> |
| \end{verbatim} |
| |
| Calling the pointer type without an argument creates a \code{NULL} |
| pointer. \code{NULL} pointers have a \code{False} boolean value: |
| \begin{verbatim} |
| >>> null_ptr = POINTER(c_int)() |
| >>> print bool(null_ptr) |
| False |
| >>> |
| \end{verbatim} |
| |
| \code{ctypes} checks for \code{NULL} when dereferencing pointers (but |
| dereferencing non-\code{NULL} pointers would crash Python): |
| \begin{verbatim} |
| >>> null_ptr[0] |
| Traceback (most recent call last): |
| .... |
| ValueError: NULL pointer access |
| >>> |
| |
| >>> null_ptr[0] = 1234 |
| Traceback (most recent call last): |
| .... |
| ValueError: NULL pointer access |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Type conversions\label{ctypes-type-conversions}} |
| |
| Usually, ctypes does strict type checking. This means, if you have |
| \code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or as the |
| type of a member field in a structure definition, only instances of |
| exactly the same type are accepted. There are some exceptions to this |
| rule, where ctypes accepts other objects. For example, you can pass |
| compatible array instances instead of pointer types. So, for |
| \code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int: |
| \begin{verbatim} |
| >>> class Bar(Structure): |
| ... _fields_ = [("count", c_int), ("values", POINTER(c_int))] |
| ... |
| >>> bar = Bar() |
| >>> bar.values = (c_int * 3)(1, 2, 3) |
| >>> bar.count = 3 |
| >>> for i in range(bar.count): |
| ... print bar.values[i] |
| ... |
| 1 |
| 2 |
| 3 |
| >>> |
| \end{verbatim} |
| |
| To set a POINTER type field to \code{NULL}, you can assign \code{None}: |
| \begin{verbatim} |
| >>> bar.values = None |
| >>> |
| \end{verbatim} |
| |
| XXX list other conversions... |
| |
| Sometimes you have instances of incompatible types. In \code{C}, you can |
| cast one type into another type. \code{ctypes} provides a \code{cast} |
| function which can be used in the same way. The \code{Bar} structure |
| defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays |
| for its \code{values} field, but not instances of other types: |
| \begin{verbatim} |
| >>> bar.values = (c_byte * 4)() |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance |
| >>> |
| \end{verbatim} |
| |
| For these cases, the \code{cast} function is handy. |
| |
| The \code{cast} function can be used to cast a ctypes instance into a |
| pointer to a different ctypes data type. \code{cast} takes two |
| parameters, a ctypes object that is or can be converted to a pointer |
| of some kind, and a ctypes pointer type. It returns an instance of |
| the second argument, which references the same memory block as the |
| first argument: |
| \begin{verbatim} |
| >>> a = (c_byte * 4)() |
| >>> cast(a, POINTER(c_int)) |
| <ctypes.LP_c_long object at ...> |
| >>> |
| \end{verbatim} |
| |
| So, \code{cast} can be used to assign to the \code{values} field of \code{Bar} |
| the structure: |
| \begin{verbatim} |
| >>> bar = Bar() |
| >>> bar.values = cast((c_byte * 4)(), POINTER(c_int)) |
| >>> print bar.values[0] |
| 0 |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Incomplete Types\label{ctypes-incomplete-types}} |
| |
| \emph{Incomplete Types} are structures, unions or arrays whose members are |
| not yet specified. In C, they are specified by forward declarations, which |
| are defined later: |
| \begin{verbatim} |
| struct cell; /* forward declaration */ |
| |
| struct { |
| char *name; |
| struct cell *next; |
| } cell; |
| \end{verbatim} |
| |
| The straightforward translation into ctypes code would be this, but it |
| does not work: |
| \begin{verbatim} |
| >>> class cell(Structure): |
| ... _fields_ = [("name", c_char_p), |
| ... ("next", POINTER(cell))] |
| ... |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in ? |
| File "<stdin>", line 2, in cell |
| NameError: name 'cell' is not defined |
| >>> |
| \end{verbatim} |
| |
| because the new \code{class cell} is not available in the class statement |
| itself. In \code{ctypes}, we can define the \code{cell} class and set the |
| \member{{\_}fields{\_}} attribute later, after the class statement: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> class cell(Structure): |
| ... pass |
| ... |
| >>> cell._fields_ = [("name", c_char_p), |
| ... ("next", POINTER(cell))] |
| >>> |
| \end{verbatim} |
| |
| Lets try it. We create two instances of \code{cell}, and let them point |
| to each other, and finally follow the pointer chain a few times: |
| \begin{verbatim} |
| >>> c1 = cell() |
| >>> c1.name = "foo" |
| >>> c2 = cell() |
| >>> c2.name = "bar" |
| >>> c1.next = pointer(c2) |
| >>> c2.next = pointer(c1) |
| >>> p = c1 |
| >>> for i in range(8): |
| ... print p.name, |
| ... p = p.next[0] |
| ... |
| foo bar foo bar foo bar foo bar |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Callback functions\label{ctypes-callback-functions}} |
| |
| \code{ctypes} allows to create C callable function pointers from Python |
| callables. These are sometimes called \emph{callback functions}. |
| |
| First, you must create a class for the callback function, the class |
| knows the calling convention, the return type, and the number and |
| types of arguments this function will receive. |
| |
| The CFUNCTYPE factory function creates types for callback functions |
| using the normal cdecl calling convention, and, on Windows, the |
| WINFUNCTYPE factory function creates types for callback functions |
| using the stdcall calling convention. |
| |
| Both of these factory functions are called with the result type as |
| first argument, and the callback functions expected argument types as |
| the remaining arguments. |
| |
| I will present an example here which uses the standard C library's |
| \function{qsort} function, this is used to sort items with the help of a |
| callback function. \function{qsort} will be used to sort an array of |
| integers: |
| \begin{verbatim} |
| >>> IntArray5 = c_int * 5 |
| >>> ia = IntArray5(5, 1, 7, 33, 99) |
| >>> qsort = libc.qsort |
| >>> qsort.restype = None |
| >>> |
| \end{verbatim} |
| |
| \function{qsort} must be called with a pointer to the data to sort, the |
| number of items in the data array, the size of one item, and a pointer |
| to the comparison function, the callback. The callback will then be |
| called with two pointers to items, and it must return a negative |
| integer if the first item is smaller than the second, a zero if they |
| are equal, and a positive integer else. |
| |
| So our callback function receives pointers to integers, and must |
| return an integer. First we create the \code{type} for the callback |
| function: |
| \begin{verbatim} |
| >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int)) |
| >>> |
| \end{verbatim} |
| |
| For the first implementation of the callback function, we simply print |
| the arguments we get, and return 0 (incremental development ;-): |
| \begin{verbatim} |
| >>> def py_cmp_func(a, b): |
| ... print "py_cmp_func", a, b |
| ... return 0 |
| ... |
| >>> |
| \end{verbatim} |
| |
| Create the C callable callback: |
| \begin{verbatim} |
| >>> cmp_func = CMPFUNC(py_cmp_func) |
| >>> |
| \end{verbatim} |
| |
| And we're ready to go: |
| \begin{verbatim} |
| >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> |
| >>> |
| \end{verbatim} |
| |
| We know how to access the contents of a pointer, so lets redefine our callback: |
| \begin{verbatim} |
| >>> def py_cmp_func(a, b): |
| ... print "py_cmp_func", a[0], b[0] |
| ... return 0 |
| ... |
| >>> cmp_func = CMPFUNC(py_cmp_func) |
| >>> |
| \end{verbatim} |
| |
| Here is what we get on Windows: |
| \begin{verbatim} |
| >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS |
| py_cmp_func 7 1 |
| py_cmp_func 33 1 |
| py_cmp_func 99 1 |
| py_cmp_func 5 1 |
| py_cmp_func 7 5 |
| py_cmp_func 33 5 |
| py_cmp_func 99 5 |
| py_cmp_func 7 99 |
| py_cmp_func 33 99 |
| py_cmp_func 7 33 |
| >>> |
| \end{verbatim} |
| |
| It is funny to see that on linux the sort function seems to work much |
| more efficient, it is doing less comparisons: |
| \begin{verbatim} |
| >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX |
| py_cmp_func 5 1 |
| py_cmp_func 33 99 |
| py_cmp_func 7 33 |
| py_cmp_func 5 7 |
| py_cmp_func 1 7 |
| >>> |
| \end{verbatim} |
| |
| Ah, we're nearly done! The last step is to actually compare the two |
| items and return a useful result: |
| \begin{verbatim} |
| >>> def py_cmp_func(a, b): |
| ... print "py_cmp_func", a[0], b[0] |
| ... return a[0] - b[0] |
| ... |
| >>> |
| \end{verbatim} |
| |
| Final run on Windows: |
| \begin{verbatim} |
| >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS |
| py_cmp_func 33 7 |
| py_cmp_func 99 33 |
| py_cmp_func 5 99 |
| py_cmp_func 1 99 |
| py_cmp_func 33 7 |
| py_cmp_func 1 33 |
| py_cmp_func 5 33 |
| py_cmp_func 5 7 |
| py_cmp_func 1 7 |
| py_cmp_func 5 1 |
| >>> |
| \end{verbatim} |
| |
| and on Linux: |
| \begin{verbatim} |
| >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX |
| py_cmp_func 5 1 |
| py_cmp_func 33 99 |
| py_cmp_func 7 33 |
| py_cmp_func 1 7 |
| py_cmp_func 5 7 |
| >>> |
| \end{verbatim} |
| |
| It is quite interesting to see that the Windows \function{qsort} function |
| needs more comparisons than the linux version! |
| |
| As we can easily check, our array sorted now: |
| \begin{verbatim} |
| >>> for i in ia: print i, |
| ... |
| 1 5 7 33 99 |
| >>> |
| \end{verbatim} |
| |
| \textbf{Important note for callback functions:} |
| |
| Make sure you keep references to CFUNCTYPE objects as long as they are |
| used from C code. \code{ctypes} doesn't, and if you don't, they may be |
| garbage collected, crashing your program when a callback is made. |
| |
| |
| \subsubsection{Accessing values exported from dlls\label{ctypes-accessing-values-exported-from-dlls}} |
| |
| Sometimes, a dll not only exports functions, it also exports |
| variables. An example in the Python library itself is the |
| \code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the |
| \programopt{-O} or \programopt{-OO} flag given on startup. |
| |
| \code{ctypes} can access values like this with the \method{in{\_}dll} class |
| methods of the type. \var{pythonapi} ìs a predefined symbol giving |
| access to the Python C api: |
| \begin{verbatim} |
| >>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag") |
| >>> print opt_flag |
| c_long(0) |
| >>> |
| \end{verbatim} |
| |
| If the interpreter would have been started with \programopt{-O}, the sample |
| would have printed \code{c{\_}long(1)}, or \code{c{\_}long(2)} if \programopt{-OO} would have |
| been specified. |
| |
| An extended example which also demonstrates the use of pointers |
| accesses the \code{PyImport{\_}FrozenModules} pointer exported by Python. |
| |
| Quoting the Python docs: \emph{This pointer is initialized to point to an |
| array of ``struct {\_}frozen`` records, terminated by one whose members |
| are all NULL or zero. When a frozen module is imported, it is searched |
| in this table. Third-party code could play tricks with this to provide |
| a dynamically created collection of frozen modules.} |
| |
| So manipulating this pointer could even prove useful. To restrict the |
| example size, we show only how this table can be read with |
| \code{ctypes}: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> |
| >>> class struct_frozen(Structure): |
| ... _fields_ = [("name", c_char_p), |
| ... ("code", POINTER(c_ubyte)), |
| ... ("size", c_int)] |
| ... |
| >>> |
| \end{verbatim} |
| |
| We have defined the \code{struct {\_}frozen} data type, so we can get the |
| pointer to the table: |
| \begin{verbatim} |
| >>> FrozenTable = POINTER(struct_frozen) |
| >>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules") |
| >>> |
| \end{verbatim} |
| |
| Since \code{table} is a \code{pointer} to the array of \code{struct{\_}frozen} |
| records, we can iterate over it, but we just have to make sure that |
| our loop terminates, because pointers have no size. Sooner or later it |
| would probably crash with an access violation or whatever, so it's |
| better to break out of the loop when we hit the NULL entry: |
| \begin{verbatim} |
| >>> for item in table: |
| ... print item.name, item.size |
| ... if item.name is None: |
| ... break |
| ... |
| __hello__ 104 |
| __phello__ -104 |
| __phello__.spam 104 |
| None 0 |
| >>> |
| \end{verbatim} |
| |
| The fact that standard Python has a frozen module and a frozen package |
| (indicated by the negative size member) is not wellknown, it is only |
| used for testing. Try it out with \code{import {\_}{\_}hello{\_}{\_}} for example. |
| |
| |
| \subsubsection{Surprises\label{ctypes-surprises}} |
| |
| There are some edges in \code{ctypes} where you may be expect something |
| else than what actually happens. |
| |
| Consider the following example: |
| \begin{verbatim} |
| >>> from ctypes import * |
| >>> class POINT(Structure): |
| ... _fields_ = ("x", c_int), ("y", c_int) |
| ... |
| >>> class RECT(Structure): |
| ... _fields_ = ("a", POINT), ("b", POINT) |
| ... |
| >>> p1 = POINT(1, 2) |
| >>> p2 = POINT(3, 4) |
| >>> rc = RECT(p1, p2) |
| >>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y |
| 1 2 3 4 |
| >>> # now swap the two points |
| >>> rc.a, rc.b = rc.b, rc.a |
| >>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y |
| 3 4 3 4 |
| >>> |
| \end{verbatim} |
| |
| Hm. We certainly expected the last statement to print \code{3 4 1 2}. |
| What happended? Here are the steps of the \code{rc.a, rc.b = rc.b, rc.a} |
| line above: |
| \begin{verbatim} |
| >>> temp0, temp1 = rc.b, rc.a |
| >>> rc.a = temp0 |
| >>> rc.b = temp1 |
| >>> |
| \end{verbatim} |
| |
| Note that \code{temp0} and \code{temp1} are objects still using the internal |
| buffer of the \code{rc} object above. So executing \code{rc.a = temp0} |
| copies the buffer contents of \code{temp0} into \code{rc} 's buffer. This, |
| in turn, changes the contents of \code{temp1}. So, the last assignment |
| \code{rc.b = temp1}, doesn't have the expected effect. |
| |
| Keep in mind that retrieving subobjects from Structure, Unions, and |
| Arrays doesn't \emph{copy} the subobject, instead it retrieves a wrapper |
| object accessing the root-object's underlying buffer. |
| |
| Another example that may behave different from what one would expect is this: |
| \begin{verbatim} |
| >>> s = c_char_p() |
| >>> s.value = "abc def ghi" |
| >>> s.value |
| 'abc def ghi' |
| >>> s.value is s.value |
| False |
| >>> |
| \end{verbatim} |
| |
| Why is it printing \code{False}? ctypes instances are objects containing |
| a memory block plus some descriptors accessing the contents of the |
| memory. Storing a Python object in the memory block does not store |
| the object itself, instead the \code{contents} of the object is stored. |
| Accessing the contents again constructs a new Python each time! |
| |
| |
| \subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}} |
| |
| \code{ctypes} provides some support for variable-sized arrays and |
| structures (this was added in version 0.9.9.7). |
| |
| The \code{resize} function can be used to resize the memory buffer of an |
| existing ctypes object. The function takes the object as first |
| argument, and the requested size in bytes as the second argument. The |
| memory block cannot be made smaller than the natural memory block |
| specified by the objects type, a \code{ValueError} is raised if this is |
| tried: |
| \begin{verbatim} |
| >>> short_array = (c_short * 4)() |
| >>> print sizeof(short_array) |
| 8 |
| >>> resize(short_array, 4) |
| Traceback (most recent call last): |
| ... |
| ValueError: minimum size is 8 |
| >>> resize(short_array, 32) |
| >>> sizeof(short_array) |
| 32 |
| >>> sizeof(type(short_array)) |
| 8 |
| >>> |
| \end{verbatim} |
| |
| This is nice and fine, but how would one access the additional |
| elements contained in this array? Since the type still only knows |
| about 4 elements, we get errors accessing other elements: |
| \begin{verbatim} |
| >>> short_array[:] |
| [0, 0, 0, 0] |
| >>> short_array[7] |
| Traceback (most recent call last): |
| ... |
| IndexError: invalid index |
| >>> |
| \end{verbatim} |
| |
| Another way to use variable-sized data types with \code{ctypes} is to use |
| the dynamic nature of Python, and (re-)define the data type after the |
| required size is already known, on a case by case basis. |
| |
| |
| \subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}} |
| |
| Enumeration types are not implemented. You can do it easily yourself, |
| using \class{c{\_}int} as the base class. |
| |
| \code{long double} is not implemented. |
| % Local Variables: |
| % compile-command: "make.bat" |
| % End: |
| |
| |
| \subsection{ctypes reference\label{ctypes-ctypes-reference}} |
| |
| |
| \subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}} |
| |
| When programming in a compiled language, shared libraries are accessed |
| when compiling/linking a program, and when the program is run. |
| |
| The purpose of the \code{find{\_}library} function is to locate a library in |
| a way similar to what the compiler does (on platforms with several |
| versions of a shared library the most recent should be loaded), while |
| the ctypes library loaders act like when a program is run, and call |
| the runtime loader directly. |
| |
| The \code{ctypes.util} module provides a function which can help to |
| determine the library to load. |
| |
| \begin{datadescni}{find_library(name)} |
| Try to find a library and return a pathname. \var{name} is the |
| library name without any prefix like \var{lib}, suffix like \code{.so}, |
| \code{.dylib} or version number (this is the form used for the posix |
| linker option \programopt{-l}). If no library can be found, returns |
| \code{None}. |
| \end{datadescni} |
| |
| The exact functionality is system dependend. |
| |
| On Linux, \code{find{\_}library} tries to run external programs |
| (/sbin/ldconfig, gcc, and objdump) to find the library file. It |
| returns the filename of the library file. Here are sone examples: |
| \begin{verbatim} |
| >>> from ctypes.util import find_library |
| >>> find_library("m") |
| 'libm.so.6' |
| >>> find_library("c") |
| 'libc.so.6' |
| >>> find_library("bz2") |
| 'libbz2.so.1.0' |
| >>> |
| \end{verbatim} |
| |
| On OS X, \code{find{\_}library} tries several predefined naming schemes and |
| paths to locate the library, and returns a full pathname if successfull: |
| \begin{verbatim} |
| >>> from ctypes.util import find_library |
| >>> find_library("c") |
| '/usr/lib/libc.dylib' |
| >>> find_library("m") |
| '/usr/lib/libm.dylib' |
| >>> find_library("bz2") |
| '/usr/lib/libbz2.dylib' |
| >>> find_library("AGL") |
| '/System/Library/Frameworks/AGL.framework/AGL' |
| >>> |
| \end{verbatim} |
| |
| On Windows, \code{find{\_}library} searches along the system search path, |
| and returns the full pathname, but since there is no predefined naming |
| scheme a call like \code{find{\_}library("c")} will fail and return |
| \code{None}. |
| |
| If wrapping a shared library with \code{ctypes}, it \emph{may} be better to |
| determine the shared library name at development type, and hardcode |
| that into the wrapper module instead of using \code{find{\_}library} to |
| locate the library at runtime. |
| |
| |
| \subsubsection{Loading shared libraries\label{ctypes-loading-shared-libraries}} |
| |
| There are several ways to loaded shared libraries into the Python |
| process. One way is to instantiate one of the following classes: |
| |
| \begin{classdesc}{CDLL}{name, mode=DEFAULT_MODE, handle=None} |
| Instances of this class represent loaded shared libraries. |
| Functions in these libraries use the standard C calling |
| convention, and are assumed to return \code{int}. |
| \end{classdesc} |
| |
| \begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None} |
| Windows only: Instances of this class represent loaded shared |
| libraries, functions in these libraries use the \code{stdcall} |
| calling convention, and are assumed to return the windows specific |
| \class{HRESULT} code. \class{HRESULT} values contain information |
| specifying whether the function call failed or succeeded, together |
| with additional error code. If the return value signals a |
| failure, an \class{WindowsError} is automatically raised. |
| \end{classdesc} |
| |
| \begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None} |
| Windows only: Instances of this class represent loaded shared |
| libraries, functions in these libraries use the \code{stdcall} |
| calling convention, and are assumed to return \code{int} by default. |
| |
| On Windows CE only the standard calling convention is used, for |
| convenience the \class{WinDLL} and \class{OleDLL} use the standard calling |
| convention on this platform. |
| \end{classdesc} |
| |
| The Python GIL is released before calling any function exported by |
| these libraries, and reaquired afterwards. |
| |
| \begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None} |
| Instances of this class behave like \class{CDLL} instances, except |
| that the Python GIL is \emph{not} released during the function call, |
| and after the function execution the Python error flag is checked. |
| If the error flag is set, a Python exception is raised. |
| |
| Thus, this is only useful to call Python C api functions directly. |
| \end{classdesc} |
| |
| All these classes can be instantiated by calling them with at least |
| one argument, the pathname of the shared library. If you have an |
| existing handle to an already loaded shard library, it can be passed |
| as the \code{handle} named parameter, otherwise the underlying platforms |
| \code{dlopen} or \method{LoadLibrary} function is used to load the library |
| into the process, and to get a handle to it. |
| |
| The \var{mode} parameter can be used to specify how the library is |
| loaded. For details, consult the \code{dlopen(3)} manpage, on Windows, |
| \var{mode} is ignored. |
| |
| \begin{datadescni}{RTLD_GLOBAL} |
| Flag to use as \var{mode} parameter. On platforms where this flag |
| is not available, it is defined as the integer zero. |
| \end{datadescni} |
| |
| \begin{datadescni}{RTLD_LOCAL} |
| Flag to use as \var{mode} parameter. On platforms where this is not |
| available, it is the same as \var{RTLD{\_}GLOBAL}. |
| \end{datadescni} |
| |
| \begin{datadescni}{DEFAULT_MODE} |
| The default mode which is used to load shared libraries. On OSX |
| 10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as |
| \var{RTLD{\_}LOCAL}. |
| \end{datadescni} |
| |
| Instances of these classes have no public methods, however |
| \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions |
| exported by the shared library can be accessed as attributes of by |
| index. Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} |
| cache their result, so calling them repeatedly returns the same object |
| each time. |
| |
| The following public attributes are available, their name starts with |
| an underscore to not clash with exported function names: |
| |
| \begin{memberdesc}{_handle} |
| The system handle used to access the library. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{_name} |
| The name of the library passed in the contructor. |
| \end{memberdesc} |
| |
| Shared libraries can also be loaded by using one of the prefabricated |
| objects, which are instances of the \class{LibraryLoader} class, either by |
| calling the \method{LoadLibrary} method, or by retrieving the library as |
| attribute of the loader instance. |
| |
| \begin{classdesc}{LibraryLoader}{dlltype} |
| Class which loads shared libraries. \code{dlltype} should be one |
| of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types. |
| |
| \method{{\_}{\_}getattr{\_}{\_}} has special behaviour: It allows to load a shared |
| library by accessing it as attribute of a library loader |
| instance. The result is cached, so repeated attribute accesses |
| return the same library each time. |
| \end{classdesc} |
| |
| \begin{methoddesc}{LoadLibrary}{name} |
| Load a shared library into the process and return it. This method |
| always returns a new instance of the library. |
| \end{methoddesc} |
| |
| These prefabricated library loaders are available: |
| |
| \begin{datadescni}{cdll} |
| Creates \class{CDLL} instances. |
| \end{datadescni} |
| |
| \begin{datadescni}{windll} |
| Windows only: Creates \class{WinDLL} instances. |
| \end{datadescni} |
| |
| \begin{datadescni}{oledll} |
| Windows only: Creates \class{OleDLL} instances. |
| \end{datadescni} |
| |
| \begin{datadescni}{pydll} |
| Creates \class{PyDLL} instances. |
| \end{datadescni} |
| |
| For accessing the C Python api directly, a ready-to-use Python shared |
| library object is available: |
| |
| \begin{datadescni}{pythonapi} |
| An instance of \class{PyDLL} that exposes Python C api functions as |
| attributes. Note that all these functions are assumed to return C |
| \code{int}, which is of course not always the truth, so you have to |
| assign the correct \member{restype} attribute to use these functions. |
| \end{datadescni} |
| |
| |
| \subsubsection{Foreign functions\label{ctypes-foreign-functions}} |
| |
| As explained in the previous section, foreign functions can be |
| accessed as attributes of loaded shared libraries. The function |
| objects created in this way by default accept any number of arguments, |
| accept any ctypes data instances as arguments, and return the default |
| result type specified by the library loader. They are instances of a |
| private class: |
| |
| \begin{classdesc*}{_FuncPtr} |
| Base class for C callable foreign functions. |
| \end{classdesc*} |
| |
| Instances of foreign functions are also C compatible data types; they |
| represent C function pointers. |
| |
| This behaviour can be customized by assigning to special attributes of |
| the foreign function object. |
| |
| \begin{memberdesc}{restype} |
| Assign a ctypes type to specify the result type of the foreign |
| function. Use \code{None} for \code{void} a function not returning |
| anything. |
| |
| It is possible to assign a callable Python object that is not a |
| ctypes type, in this case the function is assumed to return a |
| C \code{int}, and the callable will be called with this integer, |
| allowing to do further processing or error checking. Using this |
| is deprecated, for more flexible postprocessing or error checking |
| use a ctypes data type as \member{restype} and assign a callable to the |
| \member{errcheck} attribute. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{argtypes} |
| Assign a tuple of ctypes types to specify the argument types that |
| the function accepts. Functions using the \code{stdcall} calling |
| convention can only be called with the same number of arguments as |
| the length of this tuple; functions using the C calling convention |
| accept additional, unspecified arguments as well. |
| |
| When a foreign function is called, each actual argument is passed |
| to the \method{from{\_}param} class method of the items in the |
| \member{argtypes} tuple, this method allows to adapt the actual |
| argument to an object that the foreign function accepts. For |
| example, a \class{c{\_}char{\_}p} item in the \member{argtypes} tuple will |
| convert a unicode string passed as argument into an byte string |
| using ctypes conversion rules. |
| |
| New: It is now possible to put items in argtypes which are not |
| ctypes types, but each item must have a \method{from{\_}param} method |
| which returns a value usable as argument (integer, string, ctypes |
| instance). This allows to define adapters that can adapt custom |
| objects as function parameters. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{errcheck} |
| Assign a Python function or another callable to this attribute. |
| The callable will be called with three or more arguments: |
| \end{memberdesc} |
| |
| \begin{funcdescni}{callable}{result, func, arguments} |
| \code{result} is what the foreign function returns, as specified by the |
| \member{restype} attribute. |
| |
| \code{func} is the foreign function object itself, this allows to |
| reuse the same callable object to check or postprocess the results |
| of several functions. |
| |
| \code{arguments} is a tuple containing the parameters originally |
| passed to the function call, this allows to specialize the |
| behaviour on the arguments used. |
| |
| The object that this function returns will be returned from the |
| foreign function call, but it can also check the result value and |
| raise an exception if the foreign function call failed. |
| \end{funcdescni} |
| |
| \begin{excdesc}{ArgumentError()} |
| This exception is raised when a foreign function call cannot |
| convert one of the passed arguments. |
| \end{excdesc} |
| |
| |
| \subsubsection{Function prototypes\label{ctypes-function-prototypes}} |
| |
| Foreign functions can also be created by instantiating function |
| prototypes. Function prototypes are similar to function prototypes in |
| C; they describe a function (return type, argument types, calling |
| convention) without defining an implementation. The factory |
| functions must be called with the desired result type and the argument |
| types of the function. |
| |
| \begin{funcdesc}{CFUNCTYPE}{restype, *argtypes} |
| The returned function prototype creates functions that use the |
| standard C calling convention. The function will release the GIL |
| during the call. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes} |
| Windows only: The returned function prototype creates functions |
| that use the \code{stdcall} calling convention, except on Windows CE |
| where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}. The function |
| will release the GIL during the call. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes} |
| The returned function prototype creates functions that use the |
| Python calling convention. The function will \emph{not} release the |
| GIL during the call. |
| \end{funcdesc} |
| |
| Function prototypes created by the factory functions can be |
| instantiated in different ways, depending on the type and number of |
| the parameters in the call. |
| |
| \begin{funcdescni}{prototype}{address} |
| Returns a foreign function at the specified address. |
| \end{funcdescni} |
| |
| \begin{funcdescni}{prototype}{callable} |
| Create a C callable function (a callback function) from a Python |
| \code{callable}. |
| \end{funcdescni} |
| |
| \begin{funcdescni}{prototype}{func_spec\optional{, paramflags}} |
| Returns a foreign function exported by a shared library. |
| \code{func{\_}spec} must be a 2-tuple \code{(name{\_}or{\_}ordinal, library)}. |
| The first item is the name of the exported function as string, or |
| the ordinal of the exported function as small integer. The second |
| item is the shared library instance. |
| \end{funcdescni} |
| |
| \begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}} |
| Returns a foreign function that will call a COM method. |
| \code{vtbl{\_}index} is the index into the virtual function table, a |
| small nonnegative integer. \var{name} is name of the COM method. |
| \var{iid} is an optional pointer to the interface identifier which |
| is used in extended error reporting. |
| |
| COM methods use a special calling convention: They require a |
| pointer to the COM interface as first argument, in addition to |
| those parameters that are specified in the \member{argtypes} tuple. |
| \end{funcdescni} |
| |
| The optional \var{paramflags} parameter creates foreign function |
| wrappers with much more functionality than the features described |
| above. |
| |
| \var{paramflags} must be a tuple of the same length as \member{argtypes}. |
| |
| Each item in this tuple contains further information about a |
| parameter, it must be a tuple containing 1, 2, or 3 items. |
| |
| The first item is an integer containing flags for the parameter: |
| |
| \begin{datadescni}{1} |
| Specifies an input parameter to the function. |
| \end{datadescni} |
| |
| \begin{datadescni}{2} |
| Output parameter. The foreign function fills in a value. |
| \end{datadescni} |
| |
| \begin{datadescni}{4} |
| Input parameter which defaults to the integer zero. |
| \end{datadescni} |
| |
| The optional second item is the parameter name as string. If this is |
| specified, the foreign function can be called with named parameters. |
| |
| The optional third item is the default value for this parameter. |
| |
| This example demonstrates how to wrap the Windows \code{MessageBoxA} |
| function so that it supports default parameters and named arguments. |
| The C declaration from the windows header file is this: |
| \begin{verbatim} |
| WINUSERAPI int WINAPI |
| MessageBoxA( |
| HWND hWnd , |
| LPCSTR lpText, |
| LPCSTR lpCaption, |
| UINT uType); |
| \end{verbatim} |
| |
| Here is the wrapping with \code{ctypes}: |
| \begin{quote} |
| \begin{verbatim}>>> from ctypes import c_int, WINFUNCTYPE, windll |
| >>> from ctypes.wintypes import HWND, LPCSTR, UINT |
| >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) |
| >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) |
| >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) |
| >>>\end{verbatim} |
| \end{quote} |
| |
| The MessageBox foreign function can now be called in these ways: |
| \begin{verbatim} |
| >>> MessageBox() |
| >>> MessageBox(text="Spam, spam, spam") |
| >>> MessageBox(flags=2, text="foo bar") |
| >>> |
| \end{verbatim} |
| |
| A second example demonstrates output parameters. The win32 |
| \code{GetWindowRect} function retrieves the dimensions of a specified |
| window by copying them into \code{RECT} structure that the caller has to |
| supply. Here is the C declaration: |
| \begin{verbatim} |
| WINUSERAPI BOOL WINAPI |
| GetWindowRect( |
| HWND hWnd, |
| LPRECT lpRect); |
| \end{verbatim} |
| |
| Here is the wrapping with \code{ctypes}: |
| \begin{quote} |
| \begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError |
| >>> from ctypes.wintypes import BOOL, HWND, RECT |
| >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) |
| >>> paramflags = (1, "hwnd"), (2, "lprect") |
| >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags) |
| >>>\end{verbatim} |
| \end{quote} |
| |
| Functions with output parameters will automatically return the output |
| parameter value if there is a single one, or a tuple containing the |
| output parameter values when there are more than one, so the |
| GetWindowRect function now returns a RECT instance, when called. |
| |
| Output parameters can be combined with the \member{errcheck} protocol to do |
| further output processing and error checking. The win32 |
| \code{GetWindowRect} api function returns a \code{BOOL} to signal success or |
| failure, so this function could do the error checking, and raises an |
| exception when the api call failed: |
| \begin{verbatim} |
| >>> def errcheck(result, func, args): |
| ... if not result: |
| ... raise WinError() |
| ... return args |
| >>> GetWindowRect.errcheck = errcheck |
| >>> |
| \end{verbatim} |
| |
| If the \member{errcheck} function returns the argument tuple it receives |
| unchanged, \code{ctypes} continues the normal processing it does on the |
| output parameters. If you want to return a tuple of window |
| coordinates instead of a \code{RECT} instance, you can retrieve the |
| fields in the function and return them instead, the normal processing |
| will no longer take place: |
| \begin{verbatim} |
| >>> def errcheck(result, func, args): |
| ... if not result: |
| ... raise WinError() |
| ... rc = args[1] |
| ... return rc.left, rc.top, rc.bottom, rc.right |
| >>> |
| >>> GetWindowRect.errcheck = errcheck |
| >>> |
| \end{verbatim} |
| |
| |
| \subsubsection{Utility functions\label{ctypes-utility-functions}} |
| |
| \begin{funcdesc}{addressof}{obj} |
| Returns the address of the memory buffer as integer. \code{obj} must |
| be an instance of a ctypes type. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{alignment}{obj_or_type} |
| Returns the alignment requirements of a ctypes type. |
| \code{obj{\_}or{\_}type} must be a ctypes type or instance. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{byref}{obj} |
| Returns a light-weight pointer to \code{obj}, which must be an |
| instance of a ctypes type. The returned object can only be used as |
| a foreign function call parameter. It behaves similar to |
| \code{pointer(obj)}, but the construction is a lot faster. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{cast}{obj, type} |
| This function is similar to the cast operator in C. It returns a |
| new instance of \code{type} which points to the same memory block as |
| \code{obj}. \code{type} must be a pointer type, and \code{obj} must be an |
| object that can be interpreted as a pointer. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}} |
| This function creates a mutable character buffer. The returned |
| object is a ctypes array of \class{c{\_}char}. |
| |
| \code{init{\_}or{\_}size} must be an integer which specifies the size of |
| the array, or a string which will be used to initialize the array |
| items. |
| |
| If a string is specified as first argument, the buffer is made one |
| item larger than the length of the string so that the last element |
| in the array is a NUL termination character. An integer can be |
| passed as second argument which allows to specify the size of the |
| array if the length of the string should not be used. |
| |
| If the first parameter is a unicode string, it is converted into |
| an 8-bit string according to ctypes conversion rules. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}} |
| This function creates a mutable unicode character buffer. The |
| returned object is a ctypes array of \class{c{\_}wchar}. |
| |
| \code{init{\_}or{\_}size} must be an integer which specifies the size of |
| the array, or a unicode string which will be used to initialize |
| the array items. |
| |
| If a unicode string is specified as first argument, the buffer is |
| made one item larger than the length of the string so that the |
| last element in the array is a NUL termination character. An |
| integer can be passed as second argument which allows to specify |
| the size of the array if the length of the string should not be |
| used. |
| |
| If the first parameter is a 8-bit string, it is converted into an |
| unicode string according to ctypes conversion rules. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{DllCanUnloadNow}{} |
| Windows only: This function is a hook which allows to implement |
| inprocess COM servers with ctypes. It is called from the |
| DllCanUnloadNow function that the {\_}ctypes extension dll exports. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{DllGetClassObject}{} |
| Windows only: This function is a hook which allows to implement |
| inprocess COM servers with ctypes. It is called from the |
| DllGetClassObject function that the \code{{\_}ctypes} extension dll exports. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{FormatError}{\optional{code}} |
| Windows only: Returns a textual description of the error code. If |
| no error code is specified, the last error code is used by calling |
| the Windows api function GetLastError. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{GetLastError}{} |
| Windows only: Returns the last error code set by Windows in the |
| calling thread. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{memmove}{dst, src, count} |
| Same as the standard C memmove library function: copies \var{count} |
| bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be |
| integers or ctypes instances that can be converted to pointers. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{memset}{dst, c, count} |
| Same as the standard C memset library function: fills the memory |
| block at address \var{dst} with \var{count} bytes of value |
| \var{c}. \var{dst} must be an integer specifying an address, or a |
| ctypes instance. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{POINTER}{type} |
| This factory function creates and returns a new ctypes pointer |
| type. Pointer types are cached an reused internally, so calling |
| this function repeatedly is cheap. type must be a ctypes type. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pointer}{obj} |
| This function creates a new pointer instance, pointing to |
| \code{obj}. The returned object is of the type POINTER(type(obj)). |
| |
| Note: If you just want to pass a pointer to an object to a foreign |
| function call, you should use \code{byref(obj)} which is much faster. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{resize}{obj, size} |
| This function resizes the internal memory buffer of obj, which |
| must be an instance of a ctypes type. It is not possible to make |
| the buffer smaller than the native size of the objects type, as |
| given by sizeof(type(obj)), but it is possible to enlarge the |
| buffer. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{set_conversion_mode}{encoding, errors} |
| This function sets the rules that ctypes objects use when |
| converting between 8-bit strings and unicode strings. encoding |
| must be a string specifying an encoding, like \code{'utf-8'} or |
| \code{'mbcs'}, errors must be a string specifying the error handling |
| on encoding/decoding errors. Examples of possible values are |
| \code{"strict"}, \code{"replace"}, or \code{"ignore"}. |
| |
| \code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous |
| conversion rules. On windows, the initial conversion rules are |
| \code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{sizeof}{obj_or_type} |
| Returns the size in bytes of a ctypes type or instance memory |
| buffer. Does the same as the C \code{sizeof()} function. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{string_at}{address\optional{, size}} |
| This function returns the string starting at memory address |
| address. If size is specified, it is used as size, otherwise the |
| string is assumed to be zero-terminated. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{WinError}{code=None, descr=None} |
| Windows only: this function is probably the worst-named thing in |
| ctypes. It creates an instance of WindowsError. If \var{code} is not |
| specified, \code{GetLastError} is called to determine the error |
| code. If \code{descr} is not spcified, \function{FormatError} is called to |
| get a textual description of the error. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{wstring_at}{address} |
| This function returns the wide character string starting at memory |
| address \code{address} as unicode string. If \code{size} is specified, |
| it is used as the number of characters of the string, otherwise |
| the string is assumed to be zero-terminated. |
| \end{funcdesc} |
| |
| |
| \subsubsection{Data types\label{ctypes-data-types}} |
| |
| \begin{classdesc*}{_CData} |
| This non-public class is the common base class of all ctypes data |
| types. Among other things, all ctypes type instances contain a |
| memory block that hold C compatible data; the address of the |
| memory block is returned by the \code{addressof()} helper function. |
| Another instance variable is exposed as \member{{\_}objects}; this |
| contains other Python objects that need to be kept alive in case |
| the memory block contains pointers. |
| \end{classdesc*} |
| |
| Common methods of ctypes data types, these are all class methods (to |
| be exact, they are methods of the metaclass): |
| |
| \begin{methoddesc}{from_address}{address} |
| This method returns a ctypes type instance using the memory |
| specified by address which must be an integer. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{from_param}{obj} |
| This method adapts obj to a ctypes type. It is called with the |
| actual object used in a foreign function call, when the type is |
| present in the foreign functions \member{argtypes} tuple; it must |
| return an object that can be used as function call parameter. |
| |
| All ctypes data types have a default implementation of this |
| classmethod, normally it returns \code{obj} if that is an instance of |
| the type. Some types accept other objects as well. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{in_dll}{library, name} |
| This method returns a ctypes type instance exported by a shared |
| library. \var{name} is the name of the symbol that exports the data, |
| \var{library} is the loaded shared library. |
| \end{methoddesc} |
| |
| Common instance variables of ctypes data types: |
| |
| \begin{memberdesc}{_b_base_} |
| Sometimes ctypes data instances do not own the memory block they |
| contain, instead they share part of the memory block of a base |
| object. The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes |
| object that owns the memory block. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{_b_needsfree_} |
| This readonly variable is true when the ctypes data instance has |
| allocated the memory block itself, false otherwise. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{_objects} |
| This member is either \code{None} or a dictionary containing Python |
| objects that need to be kept alive so that the memory block |
| contents is kept valid. This object is only exposed for |
| debugging; never modify the contents of this dictionary. |
| \end{memberdesc} |
| |
| |
| \subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}} |
| |
| \begin{classdesc*}{_SimpleCData} |
| This non-public class is the base class of all fundamental ctypes |
| data types. It is mentioned here because it contains the common |
| attributes of the fundamental ctypes data types. \code{{\_}SimpleCData} |
| is a subclass of \code{{\_}CData}, so it inherits their methods and |
| attributes. |
| \end{classdesc*} |
| |
| Instances have a single attribute: |
| |
| \begin{memberdesc}{value} |
| This attribute contains the actual value of the instance. For |
| integer and pointer types, it is an integer, for character types, |
| it is a single character string, for character pointer types it |
| is a Python string or unicode string. |
| |
| When the \code{value} attribute is retrieved from a ctypes instance, |
| usually a new object is returned each time. \code{ctypes} does \emph{not} |
| implement original object return, always a new object is |
| constructed. The same is true for all other ctypes object |
| instances. |
| \end{memberdesc} |
| |
| Fundamental data types, when returned as foreign function call |
| results, or, for example, by retrieving structure field members or |
| array items, are transparently converted to native Python types. In |
| other words, if a foreign function has a \member{restype} of \class{c{\_}char{\_}p}, |
| you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p} |
| instance. |
| |
| Subclasses of fundamental data types do \emph{not} inherit this behaviour. |
| So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p}, |
| you will receive an instance of this subclass from the function call. |
| Of course, you can get the value of the pointer by accessing the |
| \code{value} attribute. |
| |
| These are the fundamental ctypes data types: |
| |
| \begin{classdesc*}{c_byte} |
| Represents the C signed char datatype, and interprets the value as |
| small integer. The constructor accepts an optional integer |
| initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_char} |
| Represents the C char datatype, and interprets the value as a single |
| character. The constructor accepts an optional string initializer, |
| the length of the string must be exactly one character. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_char_p} |
| Represents the C char * datatype, which must be a pointer to a |
| zero-terminated string. The constructor accepts an integer |
| address, or a string. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_double} |
| Represents the C double datatype. The constructor accepts an |
| optional float initializer. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_float} |
| Represents the C double datatype. The constructor accepts an |
| optional float initializer. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_int} |
| Represents the C signed int datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. On |
| platforms where \code{sizeof(int) == sizeof(long)} it is an alias to |
| \class{c{\_}long}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_int8} |
| Represents the C 8-bit \code{signed int} datatype. Usually an alias for |
| \class{c{\_}byte}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_int16} |
| Represents the C 16-bit signed int datatype. Usually an alias for |
| \class{c{\_}short}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_int32} |
| Represents the C 32-bit signed int datatype. Usually an alias for |
| \class{c{\_}int}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_int64} |
| Represents the C 64-bit \code{signed int} datatype. Usually an alias |
| for \class{c{\_}longlong}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_long} |
| Represents the C \code{signed long} datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_longlong} |
| Represents the C \code{signed long long} datatype. The constructor accepts |
| an optional integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_short} |
| Represents the C \code{signed short} datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_size_t} |
| Represents the C \code{size{\_}t} datatype. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_ubyte} |
| Represents the C \code{unsigned char} datatype, it interprets the |
| value as small integer. The constructor accepts an optional |
| integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_uint} |
| Represents the C \code{unsigned int} datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. On |
| platforms where \code{sizeof(int) == sizeof(long)} it is an alias for |
| \class{c{\_}ulong}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_uint8} |
| Represents the C 8-bit unsigned int datatype. Usually an alias for |
| \class{c{\_}ubyte}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_uint16} |
| Represents the C 16-bit unsigned int datatype. Usually an alias for |
| \class{c{\_}ushort}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_uint32} |
| Represents the C 32-bit unsigned int datatype. Usually an alias for |
| \class{c{\_}uint}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_uint64} |
| Represents the C 64-bit unsigned int datatype. Usually an alias for |
| \class{c{\_}ulonglong}. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_ulong} |
| Represents the C \code{unsigned long} datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_ulonglong} |
| Represents the C \code{unsigned long long} datatype. The constructor |
| accepts an optional integer initializer; no overflow checking is |
| done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_ushort} |
| Represents the C \code{unsigned short} datatype. The constructor accepts an |
| optional integer initializer; no overflow checking is done. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_void_p} |
| Represents the C \code{void *} type. The value is represented as |
| integer. The constructor accepts an optional integer initializer. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_wchar} |
| Represents the C \code{wchar{\_}t} datatype, and interprets the value as a |
| single character unicode string. The constructor accepts an |
| optional string initializer, the length of the string must be |
| exactly one character. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{c_wchar_p} |
| Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to |
| a zero-terminated wide character string. The constructor accepts |
| an integer address, or a string. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{HRESULT} |
| Windows only: Represents a \class{HRESULT} value, which contains success |
| or error information for a function or method call. |
| \end{classdesc*} |
| |
| \begin{classdesc*}{py_object} |
| Represents the C \code{PyObject *} datatype. Calling this without an |
| argument creates a \code{NULL} \code{PyObject *} pointer. |
| \end{classdesc*} |
| |
| The \code{ctypes.wintypes} module provides quite some other Windows |
| specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}. |
| Some useful structures like \code{MSG} or \code{RECT} are also defined. |
| |
| |
| \subsubsection{Structured data types\label{ctypes-structured-data-types}} |
| |
| \begin{classdesc}{Union}{*args, **kw} |
| Abstract base class for unions in native byte order. |
| \end{classdesc} |
| |
| \begin{classdesc}{BigEndianStructure}{*args, **kw} |
| Abstract base class for structures in \emph{big endian} byte order. |
| \end{classdesc} |
| |
| \begin{classdesc}{LittleEndianStructure}{*args, **kw} |
| Abstract base class for structures in \emph{little endian} byte order. |
| \end{classdesc} |
| |
| Structures with non-native byte order cannot contain pointer type |
| fields, or any other data types containing pointer type fields. |
| |
| \begin{classdesc}{Structure}{*args, **kw} |
| Abstract base class for structures in \emph{native} byte order. |
| \end{classdesc} |
| |
| Concrete structure and union types must be created by subclassing one |
| of these types, and at least define a \member{{\_}fields{\_}} class variable. |
| \code{ctypes} will create descriptors which allow reading and writing the |
| fields by direct attribute accesses. These are the |
| |
| \begin{memberdesc}{_fields_} |
| A sequence defining the structure fields. The items must be |
| 2-tuples or 3-tuples. The first item is the name of the field, |
| the second item specifies the type of the field; it can be any |
| ctypes data type. |
| |
| For integer type fields like \class{c{\_}int}, a third optional item can |
| be given. It must be a small positive integer defining the bit |
| width of the field. |
| |
| Field names must be unique within one structure or union. This is |
| not checked, only one field can be accessed when names are |
| repeated. |
| |
| It is possible to define the \member{{\_}fields{\_}} class variable \emph{after} |
| the class statement that defines the Structure subclass, this |
| allows to create data types that directly or indirectly reference |
| themselves: |
| \begin{verbatim} |
| class List(Structure): |
| pass |
| List._fields_ = [("pnext", POINTER(List)), |
| ... |
| ] |
| \end{verbatim} |
| |
| The \member{{\_}fields{\_}} class variable must, however, be defined before |
| the type is first used (an instance is created, \code{sizeof()} is |
| called on it, and so on). Later assignments to the \member{{\_}fields{\_}} |
| class variable will raise an AttributeError. |
| |
| Structure and union subclass constructors accept both positional |
| and named arguments. Positional arguments are used to initialize |
| the fields in the same order as they appear in the \member{{\_}fields{\_}} |
| definition, named arguments are used to initialize the fields with |
| the corresponding name. |
| |
| It is possible to defined sub-subclasses of structure types, they |
| inherit the fields of the base class plus the \member{{\_}fields{\_}} defined |
| in the sub-subclass, if any. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{_pack_} |
| An optional small integer that allows to override the alignment of |
| structure fields in the instance. \member{{\_}pack{\_}} must already be |
| defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no |
| effect. |
| \end{memberdesc} |
| |
| \begin{memberdesc}{_anonymous_} |
| An optional sequence that lists the names of unnamed (anonymous) |
| fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}} |
| is assigned, otherwise it will have no effect. |
| |
| The fields listed in this variable must be structure or union type |
| fields. \code{ctypes} will create descriptors in the structure type |
| that allows to access the nested fields directly, without the need |
| to create the structure or union field. |
| |
| Here is an example type (Windows): |
| \begin{verbatim} |
| class _U(Union): |
| _fields_ = [("lptdesc", POINTER(TYPEDESC)), |
| ("lpadesc", POINTER(ARRAYDESC)), |
| ("hreftype", HREFTYPE)] |
| |
| class TYPEDESC(Structure): |
| _fields_ = [("u", _U), |
| ("vt", VARTYPE)] |
| |
| _anonymous_ = ("u",) |
| \end{verbatim} |
| |
| The \code{TYPEDESC} structure describes a COM data type, the \code{vt} |
| field specifies which one of the union fields is valid. Since the |
| \code{u} field is defined as anonymous field, it is now possible to |
| access the members directly off the TYPEDESC instance. |
| \code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former |
| is faster since it does not need to create a temporary union |
| instance: |
| \begin{verbatim} |
| td = TYPEDESC() |
| td.vt = VT_PTR |
| td.lptdesc = POINTER(some_type) |
| td.u.lptdesc = POINTER(some_type) |
| \end{verbatim} |
| \end{memberdesc} |
| |
| It is possible to defined sub-subclasses of structures, they inherit |
| the fields of the base class. If the subclass definition has a |
| separate \member{{\_}fields{\_}} variable, the fields specified in this are |
| appended to the fields of the base class. |
| |
| Structure and union constructors accept both positional and |
| keyword arguments. Positional arguments are used to initialize member |
| fields in the same order as they are appear in \member{{\_}fields{\_}}. Keyword |
| arguments in the constructor are interpreted as attribute assignments, |
| so they will initialize \member{{\_}fields{\_}} with the same name, or create new |
| attributes for names not present in \member{{\_}fields{\_}}. |
| |
| |
| \subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}} |
| |
| Not yet written - please see section~\ref{ctypes-pointers}, pointers and |
| section~\ref{ctypes-arrays}, arrays in the tutorial. |
| |