mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
Merged revisions 64131,64134-64141,64143-64146 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r64131 | thomas.heller | 2008-06-11 19:58:19 +0200 (Wed, 11 Jun 2008) | 1 line Markup fixes, spelling corrections, and better wordings. Hopefully. ........ r64135 | thomas.heller | 2008-06-11 20:10:43 +0200 (Wed, 11 Jun 2008) | 1 line More doc fixes. ........ r64139 | thomas.heller | 2008-06-11 20:40:51 +0200 (Wed, 11 Jun 2008) | 1 line Smaller doc fixes. ........ r64143 | thomas.heller | 2008-06-11 21:10:22 +0200 (Wed, 11 Jun 2008) | 1 line Add versionadded marker to ctypes.c_longdouble. ........ r64146 | thomas.heller | 2008-06-11 21:58:22 +0200 (Wed, 11 Jun 2008) | 2 lines Markup fixes, thanks Georg for the help. Document ctypes.util.find_library() and ctypes.util.find_msvcrt(). ........
This commit is contained in:
parent
c856c7a2f0
commit
2fadaa2882
1 changed files with 101 additions and 90 deletions
|
@ -40,7 +40,7 @@ loads libraries which export functions using the standard ``cdecl`` calling
|
|||
convention, while *windll* libraries call functions using the ``stdcall``
|
||||
calling convention. *oledll* also uses the ``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
|
||||
code is used to automatically raise a :class:`WindowsError` exception when
|
||||
the function call fails.
|
||||
|
||||
Here are some examples for Windows. Note that ``msvcrt`` is the MS standard C
|
||||
|
@ -55,10 +55,10 @@ convention::
|
|||
>>> libc = cdll.msvcrt # doctest: +WINDOWS
|
||||
>>>
|
||||
|
||||
Windows appends the usual '.dll' file suffix automatically.
|
||||
Windows appends the usual ``.dll`` file suffix automatically.
|
||||
|
||||
On Linux, it is required to specify the filename *including* the extension to
|
||||
load a library, so attribute access does not work. Either the
|
||||
load a library, so attribute access can not be used to load libraries. Either the
|
||||
:meth:`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::
|
||||
|
||||
|
@ -107,7 +107,7 @@ UNICODE is defined or not::
|
|||
|
||||
*windll* does not try to select one of them by magic, you must access the
|
||||
version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW``
|
||||
explicitly, and then call it with normal strings or unicode strings
|
||||
explicitly, and then call it with strings or unicode strings
|
||||
respectively.
|
||||
|
||||
Sometimes, dlls export functions with names which aren't valid Python
|
||||
|
@ -422,9 +422,9 @@ to implement a :meth:`from_param` class method for them to be able to use them
|
|||
in the :attr:`argtypes` sequence. The :meth:`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 :attr:`_as_parameter_` attribute, or whatever you want to
|
||||
object itself, its :attr:`_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 ``ctypes`` instance, or something having the
|
||||
integer, string, unicode, a ``ctypes`` instance, or an object with an
|
||||
:attr:`_as_parameter_` attribute.
|
||||
|
||||
|
||||
|
@ -719,6 +719,8 @@ would cause the pointer to point to the memory location where this is stored::
|
|||
c_long(99)
|
||||
>>>
|
||||
|
||||
.. XXX Document dereferencing pointers, and that it is preferred over the .contents attribute.
|
||||
|
||||
Pointer instances can also be indexed with integers::
|
||||
|
||||
>>> pi[0]
|
||||
|
@ -765,7 +767,7 @@ Calling the pointer type without an argument creates a ``NULL`` pointer.
|
|||
>>>
|
||||
|
||||
``ctypes`` checks for ``NULL`` when dereferencing pointers (but dereferencing
|
||||
non-\ ``NULL`` pointers would crash Python)::
|
||||
invalid non-\ ``NULL`` pointers would crash Python)::
|
||||
|
||||
>>> null_ptr[0]
|
||||
Traceback (most recent call last):
|
||||
|
@ -811,9 +813,9 @@ To set a POINTER type field to ``NULL``, you can assign ``None``::
|
|||
>>> bar.values = None
|
||||
>>>
|
||||
|
||||
XXX list other conversions...
|
||||
.. XXX list other conversions...
|
||||
|
||||
Sometimes you have instances of incompatible types. In ``C``, you can cast one
|
||||
Sometimes you have instances of incompatible types. In C, you can cast one
|
||||
type into another type. ``ctypes`` provides a ``cast`` function which can be
|
||||
used in the same way. The ``Bar`` structure defined above accepts
|
||||
``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field,
|
||||
|
@ -1070,7 +1072,7 @@ crashing your program when a callback is made.
|
|||
Accessing values exported from dlls
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sometimes, a dll not only exports functions, it also exports variables. An
|
||||
Some shared libraries not only export functions, they also export variables. An
|
||||
example in the Python library itself is the ``Py_OptimizeFlag``, an integer set
|
||||
to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` flag given on
|
||||
startup.
|
||||
|
@ -1246,17 +1248,6 @@ dynamic nature of Python, and (re-)define the data type after the required size
|
|||
is already known, on a case by case basis.
|
||||
|
||||
|
||||
.. _ctypes-bugs-todo-non-implemented-things:
|
||||
|
||||
Bugs, ToDo and non-implemented things
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Enumeration types are not implemented. You can do it easily yourself, using
|
||||
:class:`c_int` as the base class.
|
||||
|
||||
``long double`` is not implemented.
|
||||
|
||||
|
||||
.. _ctypes-ctypes-reference:
|
||||
|
||||
ctypes reference
|
||||
|
@ -1615,9 +1606,8 @@ type and the argument types of the function.
|
|||
`use_last_error` does the same for the Windows error code.
|
||||
|
||||
.. versionchanged:: 2.6
|
||||
|
||||
The optional `use_errno` and `use_last_error` parameters were added
|
||||
in Python 2.6.
|
||||
The optional `use_errno` and `use_last_error` parameters were
|
||||
added.
|
||||
|
||||
|
||||
.. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)
|
||||
|
@ -1633,75 +1623,71 @@ type and the argument types of the function.
|
|||
The returned function prototype creates functions that use the Python calling
|
||||
convention. The function will *not* release the GIL during the call.
|
||||
|
||||
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.
|
||||
Function prototypes created by these factory functions can be instantiated in
|
||||
different ways, depending on the type and number of the parameters in the call:
|
||||
|
||||
|
||||
.. function:: prototype(address)
|
||||
:noindex:
|
||||
.. function:: prototype(address)
|
||||
:noindex:
|
||||
:module:
|
||||
|
||||
Returns a foreign function at the specified address.
|
||||
Returns a foreign function at the specified address which must be an integer.
|
||||
|
||||
|
||||
.. function:: prototype(callable)
|
||||
:noindex:
|
||||
.. function:: prototype(callable)
|
||||
:noindex:
|
||||
:module:
|
||||
|
||||
Create a C callable function (a callback function) from a Python ``callable``.
|
||||
Create a C callable function (a callback function) from a Python ``callable``.
|
||||
|
||||
|
||||
.. function:: prototype(func_spec[, paramflags])
|
||||
:noindex:
|
||||
.. function:: prototype(func_spec[, paramflags])
|
||||
:noindex:
|
||||
:module:
|
||||
|
||||
Returns a foreign function exported by a shared library. ``func_spec`` must be a
|
||||
2-tuple ``(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.
|
||||
Returns a foreign function exported by a shared library. ``func_spec`` must be a
|
||||
2-tuple ``(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.
|
||||
|
||||
|
||||
.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
|
||||
:noindex:
|
||||
.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
|
||||
:noindex:
|
||||
:module:
|
||||
|
||||
Returns a foreign function that will call a COM method. ``vtbl_index`` is the
|
||||
index into the virtual function table, a small non-negative integer. *name* is
|
||||
name of the COM method. *iid* is an optional pointer to the interface identifier
|
||||
which is used in extended error reporting.
|
||||
Returns a foreign function that will call a COM method. ``vtbl_index`` is the
|
||||
index into the virtual function table, a small non-negative integer. *name* is
|
||||
name of the COM method. *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 :attr:`argtypes` tuple.
|
||||
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 :attr:`argtypes` tuple.
|
||||
|
||||
The optional *paramflags* parameter creates foreign function wrappers with much
|
||||
more functionality than the features described above.
|
||||
The optional *paramflags* parameter creates foreign function wrappers with much
|
||||
more functionality than the features described above.
|
||||
|
||||
*paramflags* must be a tuple of the same length as :attr:`argtypes`.
|
||||
*paramflags* must be a tuple of the same length as :attr:`argtypes`.
|
||||
|
||||
Each item in this tuple contains further information about a parameter, it must
|
||||
be a tuple containing 1, 2, or 3 items.
|
||||
Each item in this tuple contains further information about a parameter, it must
|
||||
be a tuple containing one, two, or three items.
|
||||
|
||||
The first item is an integer containing flags for the parameter:
|
||||
The first item is an integer containing a combination of direction
|
||||
flags for the parameter:
|
||||
|
||||
1
|
||||
Specifies an input parameter to the function.
|
||||
|
||||
.. data:: 1
|
||||
:noindex:
|
||||
2
|
||||
Output parameter. The foreign function fills in a value.
|
||||
|
||||
Specifies an input parameter to the function.
|
||||
4
|
||||
Input parameter which defaults to the integer zero.
|
||||
|
||||
The optional second item is the parameter name as string. If this is specified,
|
||||
the foreign function can be called with named parameters.
|
||||
|
||||
.. data:: 2
|
||||
:noindex:
|
||||
|
||||
Output parameter. The foreign function fills in a value.
|
||||
|
||||
|
||||
.. data:: 4
|
||||
:noindex:
|
||||
|
||||
Input parameter which defaults to the integer zero.
|
||||
|
||||
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.
|
||||
The optional third item is the default value for this parameter.
|
||||
|
||||
This example demonstrates how to wrap the Windows ``MessageBoxA`` function so
|
||||
that it supports default parameters and named arguments. The C declaration from
|
||||
|
@ -1714,16 +1700,14 @@ the windows header file is this::
|
|||
LPCSTR lpCaption,
|
||||
UINT uType);
|
||||
|
||||
Here is the wrapping with ``ctypes``:
|
||||
Here is the wrapping with ``ctypes``::
|
||||
|
||||
::
|
||||
|
||||
>>> 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)
|
||||
>>>
|
||||
>>> 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)
|
||||
>>>
|
||||
|
||||
The MessageBox foreign function can now be called in these ways::
|
||||
|
||||
|
@ -1741,16 +1725,14 @@ function retrieves the dimensions of a specified window by copying them into
|
|||
HWND hWnd,
|
||||
LPRECT lpRect);
|
||||
|
||||
Here is the wrapping with ``ctypes``:
|
||||
Here is the wrapping with ``ctypes``::
|
||||
|
||||
::
|
||||
|
||||
>>> 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)
|
||||
>>>
|
||||
>>> 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)
|
||||
>>>
|
||||
|
||||
Functions with output parameters will automatically return the output parameter
|
||||
value if there is a single one, or a tuple containing the output parameter
|
||||
|
@ -1766,6 +1748,7 @@ do the error checking, and raises an exception when the api call failed::
|
|||
... if not result:
|
||||
... raise WinError()
|
||||
... return args
|
||||
...
|
||||
>>> GetWindowRect.errcheck = errcheck
|
||||
>>>
|
||||
|
||||
|
@ -1780,7 +1763,7 @@ instead, the normal processing will no longer take place::
|
|||
... raise WinError()
|
||||
... rc = args[1]
|
||||
... return rc.left, rc.top, rc.bottom, rc.right
|
||||
>>>
|
||||
...
|
||||
>>> GetWindowRect.errcheck = errcheck
|
||||
>>>
|
||||
|
||||
|
@ -1866,6 +1849,33 @@ Utility functions
|
|||
servers with ctypes. It is called from the DllGetClassObject function that the
|
||||
``_ctypes`` extension dll exports.
|
||||
|
||||
.. function:: find_library(name)
|
||||
:module: ctypes.util
|
||||
|
||||
Try to find a library and return a pathname. `name` is the library name without
|
||||
any prefix like `lib`, suffix like ``.so``, ``.dylib`` or version number (this
|
||||
is the form used for the posix linker option :option:`-l`). If no library can
|
||||
be found, returns ``None``.
|
||||
|
||||
The exact functionality is system dependent.
|
||||
|
||||
.. versionchanged:: 2.6
|
||||
Windows only: ``find_library("m")`` or
|
||||
``find_library("c")`` return the result of a call to
|
||||
``find_msvcrt()``.
|
||||
|
||||
.. function:: find_msvcrt()
|
||||
:module: ctypes.util
|
||||
|
||||
Windows only: return the filename of the VC runtype library used
|
||||
by Python, and by the extension modules. If the name of the
|
||||
library cannot be determined, ``None`` is returned.
|
||||
|
||||
If you need to free memory, for example, allocated by an extension
|
||||
module with a call to the ``free(void *)``, it is important that you
|
||||
use the function in the same library that allocated the memory.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
.. function:: FormatError([code])
|
||||
|
||||
|
@ -2154,6 +2164,7 @@ These are the fundamental ctypes data types:
|
|||
optional float initializer. On platforms where ``sizeof(long
|
||||
double) == sizeof(double)`` it is an alias to :class:`c_double`.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
.. class:: c_float
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue