mirror of https://github.com/python/cpython
49 lines
3.0 KiB
Plaintext
49 lines
3.0 KiB
Plaintext
|
Preliminary notes/documentation for the calldll module, version 0.2.
|
||
|
|
====================================================================
|
||
|
|
|
||
|
|
Calldll allows you to call random C functions from python without writing any
|
||
|
|
C code. It is mainly meant to call MacOS toolbox routines for which no Python
|
||
|
|
wrapper module is available. It is also incomplete, in that only a few argument
|
||
|
|
types are currently supported. Please let me know which other argument types
|
||
|
|
you need, and/or whether you have any ideas on a general "escape" allowing people
|
||
|
|
to pass anything.
|
||
|
|
|
||
|
|
The module exports three functions:
|
||
|
|
- symtable = getlibrary(libraryname)
|
||
|
|
Get a reference to import library libraryname. "InterfaceLib" is the most commonly
|
||
|
|
used one, containing most toolbox routines. The symbol table can be used
|
||
|
|
to lookup routines to be passed to newcall: "symtable.WaitNextEvent" will
|
||
|
|
return the address of routine WaitNextEvent. and so will "symtable['WaitNextEvent']".
|
||
|
|
The symtable is a mapping, so you can use keys() and len(...) to inspect it.
|
||
|
|
- symtable = getdiskfragment(file)
|
||
|
|
Load the specified file (given by fsspec or filename) and return a reference to
|
||
|
|
its symboltable.
|
||
|
|
- callable = newcall(routine, returntype, [argtype, ...])
|
||
|
|
Return a callable object. You specify the C routine to be called (as explained above),
|
||
|
|
the type of the return value and the argument types. The resulting object can
|
||
|
|
be called from Python code in the normal way, and typechecking on arguments is
|
||
|
|
performed (but, of course, if you specify incorrect argument types in this call
|
||
|
|
you may well crash your machine). Printing a callable will give you a description
|
||
|
|
of the (C-) calling sequence.
|
||
|
|
|
||
|
|
The C return value can be one of 'None', 'Byte', 'Short', 'Long', 'Pstring' (a pascal
|
||
|
|
string returned by address, copied to a Python string), 'Cobject' (a wrapper around a void
|
||
|
|
pointer), 'Handle' (a new handle, returned as a Res.Resource object) or 'OSErr' (which raises
|
||
|
|
MacOS.Error if non-zero).
|
||
|
|
|
||
|
|
Arguments can be any of 'InByte', 'InShort', 'InLong', 'InString' (a python string, with the
|
||
|
|
address of the data passed to the C routine, so be careful!), 'InPstring' (a python string copied
|
||
|
|
to a Str255 and passed by address), 'InCobject', 'InHandle', 'OutByte' (storage is allocated for
|
||
|
|
a single byte, the address passed to C and the resulting value returned to Python), 'OutShort',
|
||
|
|
'OutLong', 'OutPstring' (again: storage pre-allocated and the address passed to C), 'OutCobject'
|
||
|
|
(storage for a void * is allocated, this void ** is passed to C and the resulting void * is
|
||
|
|
encapsulated in the Cobject returned) or 'OutHandle' (ditto, which means that this is usually *not*
|
||
|
|
what you use, you normally use 'InHandle' because most toolbox calls expect you to preallocate
|
||
|
|
the handle).
|
||
|
|
|
||
|
|
All values to be returned (from the return value and the Out arguments) are collected. If there
|
||
|
|
aren't any None is returned, if there is one value this value is returned, if there are multiple
|
||
|
|
values a tuple is returned.
|
||
|
|
|
||
|
|
There is test code in testcalldll.py, and a minimal example in samplecalldll.py.
|