14.14.2.5 Utility functions

Python 2.5

previous page next page

14.14.2.5 Utility functions

addressof( obj): Returns the address of the memory buffer as integer. obj must be an instance of a ctypes type.

alignment( obj_or_type): Returns the alignment requirements of a ctypes type. obj_or_type must be a ctypes type or instance.

byref( obj): Returns a light-weight pointer to 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 pointer(obj), but the construction is a lot faster.

cast( obj, type): This function is similar to the cast operator in C. It returns a new instance of type which points to the same memory block as obj. type must be a pointer type, and obj must be an object that can be interpreted as a pointer.

create_string_buffer( init_or_size[, size])

This function creates a mutable character buffer. The returned object is a ctypes array of c_char.

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.

create_unicode_buffer( init_or_size[, size])

This function creates a mutable unicode character buffer. The returned object is a ctypes array of c_wchar.

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.

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.

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 _ctypes extension dll exports.

FormatError( [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.

GetLastError( ): Windows only: Returns the last error code set by Windows in the calling thread.

memmove( dst, src, count): Same as the standard C memmove library function: copies count bytes from src to dst. dst and src must be integers or ctypes instances that can be converted to pointers.

memset( dst, c, count): Same as the standard C memset library function: fills the memory block at address dst with count bytes of value c. dst must be an integer specifying an address, or a ctypes instance.

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.

pointer( obj): This function creates a new pointer instance, pointing to 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 byref(obj) which is much faster.

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.

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 'utf-8' or 'mbcs', errors must be a string specifying the error handling on encoding/decoding errors. Examples of possible values are "strict", "replace", or "ignore".
set_conversion_mode returns a 2-tuple containing the previous conversion rules. On windows, the initial conversion rules are ('mbcs', 'ignore'), on other systems ('ascii', 'strict').

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.

string_at( address[, 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.

WinError( code=None, descr=None): Windows only: this function is probably the worst-named thing in ctypes. It creates an instance of WindowsError. If code is not specified, GetLastError is called to determine the error code. If descr is not spcified, FormatError is called to get a textual description of the error.

wstring_at( address): This function returns the wide character string starting at memory address address as unicode string. If size is specified, it is used as the number of characters of the string, otherwise the string is assumed to be zero-terminated.

See About this document... for information on suggesting changes.

previous page start next page