#!/usr/bin/perl
#
# Sample D-Bus "listener". This shows how you can listen to various signals
# that may be emitted on a D-Bus message bus.
#
# Author:  Madison Kelly (mkelly@alteeve.ca)
# Updated: 2008/07/14
# Plug:    http://tle-bu.org
#
# Source code released under the GPLv3.
#  - http://www.gnu.org/licenses/gpl-3.0.txt
# Documentation released under Creative Commons
# Attribution-Noncommercial-Share Alike 3.0 License.
#  - http://creativecommons.org/licenses/by-nc-sa/3.0/
#
# This program file is not meant to be fast or event particularly sane. It's
# primary goal is to show as many possible methods and functions available in
# the Net::DBus* modules as possible in a format that is easy to follow for a
# new user. You will want to read up more on the best way to do various things
# one you have your own code working.
#
# The examples here are somewhat based on the example scripts provided by the
# Net::DBus module. Please check the scripts under the 'examples' directory if
# you would like to see the similarities.
#

# Being good little coder, I make things die early and loudly.
use strict;
use warnings;

# Load in the Net::DBus core module.
use Net::DBus;

# Now load the reactor module used to create our event loop that will listen
# for messages from signals I subscribe to.
use Net::DBus::Reactor;

# Create a connection to the Freedesktop.org 'session' bus, which is the bus
# accessible by the user invoking this module only.
my $bus=Net::DBus->session();

# Get a connection to the service with the well known name
# 'org.tle-bu.SampleService'. I know to use this service name because the
# author of the service made it clearly known in their always-excelent 
# documentation. :) In our case, this is the service name used in the 'main'
# package in the 'service_01.pl' file.
my $service=$bus->get_service("org.tle-bu.SampleService");

# Now that I have a connection to the service, I need to connect to the methods
# exported under the object path '/org/tle_bu/DBusExampleObject' published
# under the interface 'org.tle_bu.DBusExampleInterface'. Technically, I could
# leave off the interface decleration *IF* I can be sure the
# 'DBusExampleObject' object is uniquly named within this service *AND* the
# remote object supports introspection. However, it is always safe to be
# specific.
my $object=$service->get_object("/org/tle_bu/DBusExampleObject", "org.tle_bu.DBusExampleInterface");

# This will be a simple subroutine that will be called when the signal we care
# about is received. The message sent by the signal will be passed into this.
sub handleMessage
{
	# Pick up the message emitted by the signal.
	my $message=shift;
	
	# Print the message to the terminal showing the message we received
	# from the signal.
	print "Received signal: [$message].\n";
	
	return;
}

# I need to know the name of the signal being emitted. In this case, I know it
# is called "signalMessage" and is emitted under the object I created above.
$object->connect_to_signal("signalMessage", \&handleMessage);
print "Now listening to 'signalMessage' signals.\n";

# Now I need to create my event reactor which will keep the program alive and
# react to signals coming from the D-Bus message bus.
my $reactor=Net::DBus::Reactor->main();

# Now start the reactor loop. This will keep this program alive until it is
# killed by a signal.
$reactor->run();

# Exit cleanly when the reactor loop completes.
exit 0;
