NAME
Ekahau::Events - Event-driven interface to Ekahau location sensing system
SYNOPSIS
The Ekahau::Events class provides an event-driven interface to the Ekahau location sensing system's YAX protocol.
This class inherits from Ekahau::Base, and you can use methods from that class. An alternative, synchronous interface is provided by the Ekahau class.
DESCRIPTION
This class implements methods for registering event handlers to receive particular Ekahau responses, and dispatching events based on responses received from Ekahau. Requests can be sent using methods available from Ekahau::Base.
Constructor
This class uses Ekahau::Base::new as its constructor.
Methods
register_handler ( $tag, $event, $handler )
Registers an event handling sub for the given tag and event. $tag and $event should be strings representing the tag and event to be handled, and $handler is a subroutine reference.
Both the tag and event must match for the handler to be called. If one or the other is undef, events with any value for that property will be handled by $handler; if both are undef, any event will be handled by the given $handler.
When dispatchone is looking for an event handler, it will first look for a registered handler matching both $tag and $event, then matching just $tag, then matching just $event, and finally the "default handler" registered with both $tag and $event set to undef. If none of these match, the event is ignored.
If an event matches, $handler will be called with an Ekahau::Response object as the first parameter, followed by the tag, followed by the event.
Each handler takes up a small amount of memory, so make sure you call unregister_handler when you no longer need to handle the event. If you're just handling a single event one time, consider using register_handler_once, which automatically unregisters the event afterwards.
register_handler_once ( $tag, $event, $handler )
Registers an event handling sub for the given tag and event, just like register_handler, but when the event completes automatically unregisters the handler.
This is useful for simple requests with simple responses, to avoid leaking memory.
unregister_handler ( $tag, $event )
Unregister the handler for the given $tag and $event.
dispatch ( )
Read pending events from the Ekahau server, and call the registered handler for each of them. This call will block; to avoid that, you should first use the Ekahau::Base::can_read method or select on the filehandles returned by Ekahau::Base::select_handles.
dispatchone ( $event )
Dispatch a single event to the appropriate handler. Generally you won't call this yourself, relying on dispatch to do it for you.
AUTHOR
Scott Gifford <gifford@umich.edu>, <sgifford@suspectclass.com>
Copyright (C) 2005 The Regents of the University of Michigan.
See the file LICENSE included with the distribution for license information.