Mac/Demo/calldll/readme

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.