mirror of https://github.com/python/cpython
New docs for ctypes.
This commit is contained in:
Thomas Heller
parent
9a7e4451d2
commit
82578c895c
|
|
@ -245,7 +245,6 @@ and how to embed it in other applications.
|
|||
\input{libplatform}
|
||||
\input{liberrno}
|
||||
\input{libctypes}
|
||||
\input{libctypesref}
|
||||
|
||||
\input{libsomeos} % Optional Operating System Services
|
||||
\input{libselect}
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,457 +0,0 @@
|
|||
\subsection{ctypes reference\label{ctypes-reference}}
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% functions
|
||||
\subsubsection{ctypes functions}
|
||||
|
||||
\begin{funcdesc}{addressof}{obj}
|
||||
Returns the address of the memory buffer as integer. \var{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.
|
||||
\var{obj_or_type} must be a ctypes type or an instance.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{excclassdesc}{ArgumentError}{}
|
||||
This exception is raised when a foreign function call cannot convert
|
||||
one of the passed arguments.
|
||||
\end{excclassdesc}
|
||||
|
||||
\begin{funcdesc}{byref}{obj}
|
||||
Returns a light-weight pointer to \var{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 \var{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}
|
||||
|
||||
% XXX separate section for CFUNCTYPE, WINFUNCTYPE, PYFUNCTYPE?
|
||||
|
||||
\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes}
|
||||
This is a factory function that returns a function prototype. The
|
||||
function prototype describes a function that has a result type of
|
||||
\code{restype}, and accepts arguments as specified by \code{argtypes}.
|
||||
The function prototype can be used to construct several kinds of
|
||||
functions, depending on how the prototype is called.
|
||||
|
||||
The prototypes returned by \code{CFUNCTYPE} or \code{PYFUNCTYPE}
|
||||
create functions that use the standard C calling convention,
|
||||
prototypes returned from \code{WINFUNCTYPE} (on Windows) use the
|
||||
\code{__stdcall} calling convention.
|
||||
|
||||
Functions created by calling the \code{CFUNCTYPE} and
|
||||
\code{WINFUNCTYPE} prototypes release the Python GIL
|
||||
before entering the foreign function, and acquire it back after
|
||||
leaving the function code.
|
||||
|
||||
% XXX differences between CFUNCTYPE / WINFUNCTYPE / PYFUNCTYPE
|
||||
|
||||
\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 \code{c_char}.
|
||||
|
||||
\var{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 \code{c_wchar}.
|
||||
|
||||
\var{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
|
||||
\code{DllCanUnloadNow} function that the \code{_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
|
||||
\code{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 \code{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 \code{memmove} library function: copies
|
||||
\var{count} bytes from \code{src} to \code{dst}. \code{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 \code{memset} library function: fills the
|
||||
memory clock at address \code{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. \var{type} must be a ctypes type.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pointer}{obj}
|
||||
This function creates a new pointer instance, pointing to \var{obj}.
|
||||
The returned object is of the type \code{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}{PYFUNCTYPE}{restype, *argtypes}
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{pythonapi}{}
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{resize}{obj, size}
|
||||
This function resizes the internal memory buffer of \var{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
|
||||
\code{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. \var{encoding} must be a
|
||||
string specifying an encoding, like 'utf-8' or 'mbcs', \var{errors}
|
||||
must be a string specifying the error handling on encoding/decoding
|
||||
errors. Examples of possible values are ``strict'', ``replace'', or
|
||||
``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 sizeof() function.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{string_at}{address\optional{size}}
|
||||
This function returns the string starting at memory address
|
||||
\var{address}. If \var{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 \code{WindowsError}. If \var{code}
|
||||
is not specified, \code{GetLastError} is called to determine the error
|
||||
code. If \var{descr} is not spcified, \var{FormatError} is called to
|
||||
get a textual description of the error.
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes}
|
||||
\end{funcdesc}
|
||||
|
||||
\begin{funcdesc}{wstring_at}{address}
|
||||
This function returns the wide character string starting at memory
|
||||
address \var{address} as unicode string. If \var{size} is specified,
|
||||
it is used as size, otherwise the string is assumed to be
|
||||
zero-terminated.
|
||||
\end{funcdesc}
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% data types
|
||||
\subsubsection{data types}
|
||||
|
||||
ctypes defines a lot of C compatible datatypes, and also allows to
|
||||
define your own types. Among other things, a ctypes type instance
|
||||
holds a memory block that contains C compatible data.
|
||||
|
||||
\begin{classdesc}{_ctypes._CData}{}
|
||||
This non-public class is the base class of all ctypes data types. It
|
||||
is mentioned here because it contains the common methods of the ctypes
|
||||
data types.
|
||||
\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 \code{address}.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{from_param}{obj}
|
||||
This method adapts \code{obj} to a ctypes type.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}{in_dll}{name, library}
|
||||
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}
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% simple data types
|
||||
\subsubsection{simple data types}
|
||||
|
||||
\begin{classdesc}{_ctypes._SimpleCData}{}
|
||||
This non-public class is the base class of all ctypes data types. It
|
||||
is mentioned here because it contains the common attributes of the
|
||||
ctypes data types.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{memberdesc}{value}
|
||||
This attribute contains the actual value of the instance. For integer
|
||||
types, it is an integer.
|
||||
\end{memberdesc}
|
||||
|
||||
Here are the simple ctypes data types:
|
||||
|
||||
\begin{classdesc}{c_byte}{\optional{value}}
|
||||
Represents a C \code{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}{\optional{value}}
|
||||
Represents a C \code{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}{\optional{value}}
|
||||
Represents a C \code{char *} datatype, which must be a pointer to a
|
||||
zero-terminated string. The constructor accepts an integer address,
|
||||
or a string.
|
||||
% XXX Explain the difference to POINTER(c_char)
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_double}{\optional{value}}
|
||||
Represents a C \code{double} datatype. The constructor accepts an
|
||||
optional float initializer.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_float}{\optional{value}}
|
||||
Represents a C \code{double} datatype. The constructor accepts an
|
||||
optional float initializer.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_int}{\optional{value}}
|
||||
Represents a C \code{signed int} datatype. The constructor accepts an
|
||||
optional integer initializer; no overflow checking is done. On
|
||||
platforms where \code{sizeof(int) == sizeof(long)} \var{c_int} is an
|
||||
alias to \var{c_long}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_int16}{\optional{value}}
|
||||
Represents a C 16-bit \code{signed int} datatype. Usually an alias
|
||||
for \var{c_short}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_int32}{\optional{value}}
|
||||
Represents a C 32-bit \code{signed int} datatype. Usually an alias
|
||||
for \code{c_int}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_int64}{\optional{value}}
|
||||
Represents a C 64-bit \code{signed int} datatype. Usually an alias
|
||||
for \code{c_longlong}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_int8}{\optional{value}}
|
||||
Represents a C 8-bit \code{signed int} datatype. Usually an alias for \code{c_byte}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_long}{\optional{value}}
|
||||
Represents a C \code{signed long} datatype. The constructor accepts
|
||||
an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_longlong}{\optional{value}}
|
||||
Represents a C \code{signed long long} datatype. The constructor
|
||||
accepts an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_short}{\optional{value}}
|
||||
Represents a C \code{signed short} datatype. The constructor accepts
|
||||
an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_size_t}{\optional{value}}
|
||||
Represents a C \code{size_t} datatype.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_ubyte}{\optional{value}}
|
||||
Represents a C \code{unsigned 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_uint}{\optional{value}}
|
||||
Represents a 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)} \var{c_int} is an
|
||||
alias to \var{c_long}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_uint16}{\optional{value}}
|
||||
Represents a C 16-bit \code{unsigned int} datatype. Usually an alias
|
||||
for \code{c_ushort}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_uint32}{\optional{value}}
|
||||
Represents a C 32-bit \code{unsigned int} datatype. Usually an alias
|
||||
for \code{c_uint}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_uint64}{\optional{value}}
|
||||
Represents a C 64-bit \code{unsigned int} datatype. Usually an alias
|
||||
for \code{c_ulonglong}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_uint8}{\optional{value}}
|
||||
Represents a C 8-bit \code{unsigned int} datatype. Usually an alias
|
||||
for \code{c_ubyte}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_ulong}{\optional{value}}
|
||||
Represents a C \code{unsigned long} datatype. The constructor accepts
|
||||
an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_ulonglong}{\optional{value}}
|
||||
Represents a C \code{unsigned long long} datatype. The constructor
|
||||
accepts an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_ushort}{\optional{value}}
|
||||
Represents a C \code{unsigned short} datatype. The constructor accepts
|
||||
an optional integer initializer; no overflow checking is done.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_void_p}{\optional{value}}
|
||||
Represents a C \code{void *} type. The value is represented as
|
||||
integer. The constructor accepts an optional integer initializer.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{c_wchar}{\optional{value}}
|
||||
Represents a 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}{\optional{value}}
|
||||
Represents a 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.
|
||||
% XXX Explain the difference to POINTER(c_wchar)
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{HRESULT}{}
|
||||
Windows only: Represents a \code{HRESULT} value, which contains
|
||||
success or error information for a function or method call.
|
||||
\end{classdesc}
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% structured data types
|
||||
\subsubsection{structured data types}
|
||||
|
||||
\begin{classdesc}{BigEndianStructure}{}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{LittleEndianStructure}{}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{Structure}{}
|
||||
Base class for Structure data types.
|
||||
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{Union}{}
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
% libraries
|
||||
\subsubsection{libraries}
|
||||
|
||||
\begin{classdesc}{CDLL}{name, mode=RTLD_LOCAL, handle=None}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{datadesc}{cdll}
|
||||
\end{datadesc}
|
||||
|
||||
\begin{classdesc}{LibraryLoader}{dlltype}
|
||||
|
||||
\begin{memberdesc}{LoadLibrary}{name, mode=RTLD_LOCAL, handle=None}
|
||||
\end{memberdesc}
|
||||
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{OleDLL}{name, mode=RTLD_LOCAL, handle=None}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{datadesc}{oledll}
|
||||
\end{datadesc}
|
||||
|
||||
\begin{classdesc}{py_object}{}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{PyDLL}{name, mode=RTLD_LOCAL, handle=None}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{datadesc}{pydll}{}
|
||||
\end{datadesc}
|
||||
|
||||
\begin{datadesc}{RTLD_GLOBAL}
|
||||
\end{datadesc}
|
||||
|
||||
\begin{datadesc}{RTLD_LOCAL}
|
||||
\end{datadesc}
|
||||
|
||||
\begin{classdesc}{WinDLL}{name, mode=RTLD_LOCAL, handle=None}
|
||||
\end{classdesc}
|
||||
|
||||
\begin{datadesc}{windll}
|
||||
\end{datadesc}
|
||||
|
||||
Loading…
Reference in New Issue