blob: 1e64dfe0d8a14a5f050009964c7304a49c61e3cf [file] [log] [blame]
Jack Jansencd219d51999-03-17 21:44:07 +00001Preliminary notes/documentation for the calldll module, version 0.2.
2====================================================================
3
4Calldll allows you to call random C functions from python without writing any
5C code. It is mainly meant to call MacOS toolbox routines for which no Python
6wrapper module is available. It is also incomplete, in that only a few argument
7types are currently supported. Please let me know which other argument types
8you need, and/or whether you have any ideas on a general "escape" allowing people
9to pass anything.
10
Jack Jansencd219d51999-03-17 21:44:07 +000011The module exports three functions:
12- symtable = getlibrary(libraryname)
13 Get a reference to import library libraryname. "InterfaceLib" is the most commonly
14 used one, containing most toolbox routines. The symbol table can be used
15 to lookup routines to be passed to newcall: "symtable.WaitNextEvent" will
16 return the address of routine WaitNextEvent. and so will "symtable['WaitNextEvent']".
17 The symtable is a mapping, so you can use keys() and len(...) to inspect it.
18- symtable = getdiskfragment(file)
19 Load the specified file (given by fsspec or filename) and return a reference to
20 its symboltable.
21- callable = newcall(routine, returntype, [argtype, ...])
22 Return a callable object. You specify the C routine to be called (as explained above),
23 the type of the return value and the argument types. The resulting object can
24 be called from Python code in the normal way, and typechecking on arguments is
25 performed (but, of course, if you specify incorrect argument types in this call
26 you may well crash your machine). Printing a callable will give you a description
27 of the (C-) calling sequence.
28
29The C return value can be one of 'None', 'Byte', 'Short', 'Long', 'Pstring' (a pascal
30string returned by address, copied to a Python string), 'Cobject' (a wrapper around a void
31pointer), 'Handle' (a new handle, returned as a Res.Resource object) or 'OSErr' (which raises
32MacOS.Error if non-zero).
33
34Arguments can be any of 'InByte', 'InShort', 'InLong', 'InString' (a python string, with the
35address of the data passed to the C routine, so be careful!), 'InPstring' (a python string copied
36to a Str255 and passed by address), 'InCobject', 'InHandle', 'OutByte' (storage is allocated for
37a single byte, the address passed to C and the resulting value returned to Python), 'OutShort',
38'OutLong', 'OutPstring' (again: storage pre-allocated and the address passed to C), 'OutCobject'
39(storage for a void * is allocated, this void ** is passed to C and the resulting void * is
40encapsulated in the Cobject returned) or 'OutHandle' (ditto, which means that this is usually *not*
41what you use, you normally use 'InHandle' because most toolbox calls expect you to preallocate
42the handle).
43
44All values to be returned (from the return value and the Out arguments) are collected. If there
45aren't any None is returned, if there is one value this value is returned, if there are multiple
46values a tuple is returned.
47
48There is test code in testcalldll.py, and a minimal example in samplecalldll.py.