Mac/Demo/calldll/readme

   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.