Class: Send::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/_aem/send.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(address, event_code, params = {}, atts = {}, transaction = KAE::KAnyTransactionID, return_id = KAE::KAutoGenerateReturnID, codecs = DefaultCodecs) ⇒ Event

Returns a new instance of Event.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/_aem/send.rb', line 23

def initialize(address, event_code, params={}, atts={}, transaction=KAE::KAnyTransactionID,
               return_id= KAE::KAutoGenerateReturnID, codecs=DefaultCodecs)
  # Create and pack a new Apple event ready for sending.
  # address : AEAddressDesc -- the target application, identified by PSN, URL, etc.
  # event_code : string -- 8-letter code indicating event's class and id, e.g. 'coregetd'
  # params : hash -- a hash of form {AE_code=>anything,...} containing zero or more event parameters (message arguments)
  # atts : hash -- a hash of form {AE_code=>anything,...} containing zero or more event attributes (event info)
  # transaction : integer -- transaction number; AEM::Application takes care of this value
  # return_id : integer  -- reply event's ID
  # codecs : Codecs -- clients can provide custom Codecs object for packing parameters and unpacking result of this event
  @_event_code = event_code
  @_codecs = codecs
  @AEM_event = _create_apple_event(event_code[0, 4], event_code[-4, 4], address, return_id, transaction)
  atts.each {|key, value| @AEM_event.put_attr(key, codecs.pack(value))}
  params.each {|key, value| @AEM_event.put_param(key, codecs.pack(value))}
end

Instance Attribute Details

#AEM_event ⇒ Object (readonly)

Clients don’t instantiate this class directly; instead, new instances are returned by AEM::Application#event.



21
22
23
 
# File 'lib/_aem/send.rb', line 21

def AEM_event
  @AEM_event
end

Instance Method Details

#_create_apple_event(event_class, event_id, target, return_id, transaction_id) ⇒ Object 



40
41
42
43
 
# File 'lib/_aem/send.rb', line 40

def _create_apple_event(event_class, event_id, target, return_id, transaction_id)
  # Hook method; may be overridden to customise how AppleEvent descriptors are created.
  return AE::AEDesc.new_apple_event(event_class, event_id, target, return_id, transaction_id)
end

#_send_apple_event(flags, timeout) ⇒ Object 



45
46
47
48
 
# File 'lib/_aem/send.rb', line 45

def _send_apple_event(flags, timeout)
  # Hook method; may be overridden to customise how events are sent.
  return @AEM_event.send_thread_safe(flags, timeout)
end

#inspect ⇒ Object Also known as: to_s 



50
51
52
 
# File 'lib/_aem/send.rb', line 50

def inspect
  return "#<AEM::Event @code=#{@_event_code}>"
end

#send(timeout = KAE::KAEDefaultTimeout, flags = KAE::KAECanSwitchLayer + KAE::KAEWaitReply) ⇒ Object 



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/_aem/send.rb', line 56

def send(timeout=KAE::KAEDefaultTimeout, flags=KAE::KAECanSwitchLayer + KAE::KAEWaitReply)
  # Send this Apple event (may be called any number of times).
  # timeout : int | KAEDefaultTimeout | KNoTimeOut -- number of ticks to wait for target process to reply before raising timeout error
  # flags : integer -- bitwise flags [1] indicating how target process should handle event
  # Result : anything -- value returned by application, if any
  #
  # [1] Should be the sum of zero or more of the following kae module constants:
  #
  # KAENoReply | KAEQueueReply | KAEWaitReply
  # KAEDontReconnect
  # KAEWantReceipt
  # KAENeverInteract | KAECanInteract | KAEAlwaysInteract
  # KAECanSwitchLayer

  begin
    reply_event = _send_apple_event(flags, timeout)
  rescue AE::MacOSError => err # The Apple Event Manager raised an error.
    if not(@_event_code == 'aevtquit' and err.to_i == -609) # Ignore invalid connection errors (-609) when quitting
      raise EventError.new(err.to_i)
    end
  else # Decode application's reply, if any. May be a return value, error number (and optional message), or nothing.
    if reply_event.type != KAE::TypeNull
      event_result = reply_event.length.times.to_h { |i|
        reply_event.get_item(i.next, KAE::TypeWildCard)
      }
      if event_result.has_key?(KAE::KeyErrorNumber) # The application raised an error.
        # Error info is unpacked using default codecs for reliability.
        e_num = DefaultCodecs.unpack(event_result[KAE::KeyErrorNumber])
        if e_num != 0 # Some apps (e.g. Finder) may return error code 0 to indicate a successful operation, so ignore this.
          raise EventError.new(e_num, event_result)
        end
      end
      if event_result.has_key?(KAE::KeyAEResult)
        # Return values are unpacked using [optionally] client-supplied codecs.
        # This allows aem clients such as appscript to customise how values are unpacked
        # (e.g. to unpack object specifier descs as appscript references instead of aem references).
        return @_codecs.unpack(event_result[KAE::KeyAEResult])
      end
    end
  end
end