Mac/Lib/toolbox/aetools.py

   1 """Tools for use in AppleEvent clients and servers.
   2
   3 pack(x) converts a Python object to an AEDesc object
   4 unpack(desc) does the reverse
   5
   6 packevent(event, parameters, attributes) sets params and attrs in an AEAppleEvent record
   7 unpackevent(event) returns the parameters and attributes from an AEAppleEvent record
   8
   9 Plus...  Lots of classes and routines that help representing AE objects,
  10 ranges, conditionals, logicals, etc., so you can write, e.g.:
  11
  12         x = Character(1, Document("foobar"))
  13
  14 and pack(x) will create an AE object reference equivalent to AppleScript's
  15
  16         character 1 of document "foobar"
  17
  18 Some of the stuff that appears to be exported from this module comes from other
  19 files: the pack stuff from aepack, the objects from aetypes.
  20
  21 """
  22
  23
  24 from types import *
  25 import AE
  26 import AppleEvents
  27 import MacOS
  28
  29 from aetypes import *
  30 from aepack import pack, unpack, coerce, AEDescType
  31
  32 # Special code to unpack an AppleEvent (which is *not* a disguised record!)
  33 # Note by Jack: No??!? If I read the docs correctly it *is*....
  34
  35 aekeywords = [
  36         'tran',
  37         'rtid',
  38         'evcl',
  39         'evid',
  40         'addr',
  41         'optk',
  42         'timo',
  43         'inte', # this attribute is read only - will be set in AESend
  44         'esrc', # this attribute is read only
  45         'miss', # this attribute is read only
  46         'from'  # new in 1.0.1
  47 ]
  48
  49 def missed(ae):
  50         try:
  51                 desc = ae.AEGetAttributeDesc('miss', 'keyw')
  52         except AE.Error, msg:
  53                 return None
  54         return desc.data
  55
  56 def unpackevent(ae):
  57         parameters = {}
  58         while 1:
  59                 key = missed(ae)
  60                 if not key: break
  61                 parameters[key] = unpack(ae.AEGetParamDesc(key, '****'))
  62         attributes = {}
  63         for key in aekeywords:
  64                 try:
  65                         desc = ae.AEGetAttributeDesc(key, '****')
  66                 except (AE.Error, MacOS.Error), msg:
  67                         if msg[0] != -1701:
  68                                 raise sys.exc_type, sys.exc_value
  69                         continue
  70                 attributes[key] = unpack(desc)
  71         return parameters, attributes
  72
  73 def packevent(ae, parameters = {}, attributes = {}):
  74         for key, value in parameters.items():
  75                 ae.AEPutParamDesc(key, pack(value))
  76         for key, value in attributes.items():
  77                 ae.AEPutAttributeDesc(key, pack(value))
  78
  79 #
  80 # Support routine for automatically generated Suite interfaces
  81 #
  82 def keysubst(arguments, keydict):
  83         """Replace long name keys by their 4-char counterparts, and check"""
  84         ok = keydict.values()
  85         for k in arguments.keys():
  86                 if keydict.has_key(k):
  87                         v = arguments[k]
  88                         del arguments[k]
  89                         arguments[keydict[k]] = v
  90                 elif k != '----' and k not in ok:
  91                         raise TypeError, 'Unknown keyword argument: %s'%k
  92
  93 def enumsubst(arguments, key, edict):
  94         """Substitute a single enum keyword argument, if it occurs"""
  95         if not arguments.has_key(key):
  96                 return
  97         v = arguments[key]
  98         ok = edict.values()
  99         if edict.has_key(v):
 100                 arguments[key] = edict[v]
 101         elif not v in ok:
 102                 raise TypeError, 'Unknown enumerator: %s'%v
 103
 104 def decodeerror(arguments):
 105         """Create the 'best' argument for a raise MacOS.Error"""
 106         errn = arguments['errn']
 107         errarg = (errn, MacOS.GetErrorString(errn))
 108         if arguments.has_key('errs'):
 109                 errarg = errarg + (arguments['errs'],)
 110         if arguments.has_key('erob'):
 111                 errarg = errarg + (arguments['erob'],)
 112         return errarg
 113
 114 class TalkTo:
 115         """An AE connection to an application"""
 116
 117         def __init__(self, signature):
 118                 """Create a communication channel with a particular application.
 119
 120                 Addressing the application is done by specifying either a
 121                 4-byte signature, an AEDesc or an object that will __aepack__
 122                 to an AEDesc.
 123                 """
 124                 if type(signature) == AEDescType:
 125                         self.target = signature
 126                 elif type(signature) == InstanceType and hasattr(signature, '__aepack__'):
 127                         self.target = signature.__aepack__()
 128                 elif type(signature) == StringType and len(signature) == 4:
 129                         self.target = AE.AECreateDesc(AppleEvents.typeApplSignature, signature)
 130                 else:
 131                         raise TypeError, "signature should be 4-char string or AEDesc"
 132                 self.send_flags = AppleEvents.kAEWaitReply
 133                 self.send_priority = AppleEvents.kAENormalPriority
 134                 self.send_timeout = AppleEvents.kAEDefaultTimeout
 135
 136         def newevent(self, code, subcode, parameters = {}, attributes = {}):
 137                 """Create a complete structure for an apple event"""
 138
 139                 event = AE.AECreateAppleEvent(code, subcode, self.target,
 140                           AppleEvents.kAutoGenerateReturnID, AppleEvents.kAnyTransactionID)
 141                 packevent(event, parameters, attributes)
 142                 return event
 143
 144         def sendevent(self, event):
 145                 """Send a pre-created appleevent, await the reply and unpack it"""
 146
 147                 reply = event.AESend(self.send_flags, self.send_priority,
 148                                           self.send_timeout)
 149                 parameters, attributes = unpackevent(reply)
 150                 return reply, parameters, attributes
 151
 152         def send(self, code, subcode, parameters = {}, attributes = {}):
 153                 """Send an appleevent given code/subcode/pars/attrs and unpack the reply"""
 154                 return self.sendevent(self.newevent(code, subcode, parameters, attributes))
 155
 156         def activate(self):
 157                 """Send 'activate' command"""
 158                 self.send('misc', 'actv')
 159
 160
 161 # Test program
 162 # XXXX Should test more, really...
 163
 164 def test():
 165         target = AE.AECreateDesc('sign', 'KAHL')
 166         ae = AE.AECreateAppleEvent('aevt', 'oapp', target, -1, 0)
 167         print unpackevent(ae)
 168         raw_input(":")
 169         ae = AE.AECreateAppleEvent('core', 'getd', target, -1, 0)
 170         obj = Character(2, Word(1, Document(1)))
 171         print obj
 172         print repr(obj)
 173         packevent(ae, {'----': obj})
 174         params, attrs = unpackevent(ae)
 175         print params['----']
 176         raw_input(":")
 177
 178 if __name__ == '__main__':
 179         test()