Ekahau::Events - Event-driven interface to Ekahau location sensing system

Ekahau documentation Contained in the Ekahau distribution.

Index

Code Index:

NAME

Top

Ekahau::Events - Event-driven interface to Ekahau location sensing system

SYNOPSIS

Top

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

Top

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

Top

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.

SEE ALSO

Top

Ekahau::Base, Ekahau.

Ekahau documentation Contained in the Ekahau distribution. 
package Ekahau::Events;
use base 'Ekahau::Base'; our $VERSION = $Ekahau::Base::VERSION;

# Written by Scott Gifford <gifford@umich.edu>
# Copyright (C) 2004 The Regents of the University of Michigan.
# See the file LICENSE included with the distribution for license
# information.

use warnings;
use strict;

use base 'Exporter';
our %EXPORT_TAGS = (events => [ qw(

EKAHAU_EVENT_DEVICE_LIST EKAHAU_EVENT_DEVICE_PROPERTIES
EKAHAU_EVENT_AREA_ESTIMATE EKAHAU_EVENT_LOCATION_ESTIMATE
EKAHAU_EVENT_LOCATION_CONTEXT EKAHAU_EVENT_MAP_IMAGE
EKAHAU_EVENT_AREA_LIST EKAHAU_EVENT_STOP_AREA_TRACK_OK
EKAHAU_EVENT_STOP_LOCATION_TRACK_OK
EKAHAU_EVENT_ERROR 
EKAHAU_EVENT_ANY EKAHAU_EVENT_ANY_TAG
				   )]);
our @EXPORT_OK = (@{$EXPORT_TAGS{events}});

use constant EKAHAU_EVENT_DEVICE_LIST => 'DEVICE_LIST';
use constant EKAHAU_EVENT_DEVICE_PROPERTIES => 'DEVICE_PROPERTIES';
use constant EKAHAU_EVENT_AREA_ESTIMATE => 'AREA_ESTIMATE';
use constant EKAHAU_EVENT_LOCATION_ESTIMATE => 'LOCATION_ESTIMATE';
use constant EKAHAU_EVENT_LOCATION_CONTEXT => 'CONTEXT';
use constant EKAHAU_EVENT_MAP_IMAGE => 'MAP';
use constant EKAHAU_EVENT_AREA_LIST => 'AREALIST';
use constant EKAHAU_EVENT_STOP_AREA_TRACK_OK => 'STOP_AREA_TRACK_OK';
use constant EKAHAU_EVENT_STOP_LOCATION_TRACK_OK => 'STOP_LOCATION_TRACK_OK';
use constant EKAHAU_EVENT_ERROR => 'ERROR';
use constant EKAHAU_EVENT_ANY => '';
use constant EKAHAU_EVENT_ANY_TAG => '';



sub register_handler
{
    my $self = shift;
    my($tag,$event,$handler) = @_;
    
    $tag ||= '';
    $event ||= '';
    
    warn 'EVENTS: '.($handler?"Registered":"Unregistered")." event for tag '$tag', event '$event'\n"
	if ($ENV{EVENTS_VERBOSE});
    $self->{_handler}{$tag}{$event} = $handler;
}


sub register_handler_once
{
    my $self = shift;
    my($tag,$event,$handler) = @_;

    $self->register_handler($tag,$event,sub { $self->unregister_handler($tag,$event); $handler->(@_); });
}


sub unregister_handler
{
    my $self = shift;
    $self->register_handler($_[0],$_[1],undef);
}


sub dispatch
{
    my $self = shift;

    $self->readsome();
    while (my $ev = $self->getpending)
    {
	$self->dispatchone($ev);
    }
}


sub dispatchone
{
    my $self = shift;
    my($ev)=@_;
    my $handler;

    my $cmd = $ev->error ? 'ERROR' : $ev->{cmd};
    my $tag = $ev->{tag};

    if (      ($handler = $self->{_handler}{$tag}{$cmd})
	   or ($handler = $self->{_handler}{$tag}{''})
	   or ($handler = $self->{_handler}{''}{$cmd})
           or ($handler = $self->{_handler}{''}{''}))
    {
        $handler->($ev,$tag,$cmd);
    }
    # Unhandled event, just ignore.
}



1;