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