From cc7570fd900185f6b81c0c1b5b5a852b47c6ed80 Mon Sep 17 00:00:00 2001 From: Thomas Heller Date: Fri, 26 May 2006 19:43:45 +0000 Subject: [PATCH] Write more docs. --- Doc/lib/libctypesref.tex | 192 +++++++++++++++++++++++++++++++++++---- 1 file changed, 175 insertions(+), 17 deletions(-) diff --git a/Doc/lib/libctypesref.tex b/Doc/lib/libctypesref.tex index 0c39231168c..6d950f4a89f 100644 --- a/Doc/lib/libctypesref.tex +++ b/Doc/lib/libctypesref.tex @@ -1,5 +1,6 @@ \subsection{ctypes reference\label{ctypes-reference}} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % functions \subsubsection{ctypes functions} @@ -14,6 +15,8 @@ Returns the alignment requirements of a ctypes type. \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} @@ -24,9 +27,33 @@ 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}} @@ -67,35 +94,52 @@ unicode string according to ctypes conversion rules. \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} exported function that the \code{_ctypes} -extension module exports. +\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} exported function that the \code{_ctypes} -extension module exports. +\code{DllGetClassObject} function that the \code{_ctypes} +extension dll exports. \end{funcdesc} -\begin{funcdesc}{FormatError}{} -Windows only: +\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: +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}{} +\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}{} +\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} @@ -104,27 +148,56 @@ Windows only: \begin{funcdesc}{pythonapi}{} \end{funcdesc} -\begin{funcdesc}{resize}{} +\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}{} +\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}{} +\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} +\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}{} +\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} @@ -132,9 +205,47 @@ 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 @@ -148,6 +259,10 @@ 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}} @@ -206,41 +321,78 @@ 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} @@ -251,12 +403,17 @@ Represents a C \code{size_t} datatype. \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} @@ -264,10 +421,11 @@ Represents a C \code{size_t} datatype. \begin{datadesc}{cdll} \end{datadesc} -\begin{classdesc}{HRESULT}{} -\end{classdesc} - \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}