File Coverage

blib/lib/Net/Shoutcast/Admin/Listener.pm

Criterion	Covered	Total	%
statement	12	31	38.7
branch	0	4	0.0
condition			n/a
subroutine	4	9	44.4
pod	5	5	100.0
total	21	49	42.8

package Net::Shoutcast::Admin::Listener;
# $Id: Listener.pm 315 2008-03-19 00:07:39Z davidp $

use warnings;
use strict;
use Carp;

use vars qw($VERSION);
$VERSION = '0.01';


=head1 NAME

Net::Shoutcast::Admin::Listener - object to represent a listener


=head1 DESCRIPTION

An object representing a listener, returned by Net::Shoutcast::Admin.


=head1 SYNOPSIS

    use Net::Shoutcast::Admin;

    my $shoutcast = Net::Shoutcast::Admin->new(
                                    host => 'server hostname',
                                    port => 8000,
                                    admin_password => 'mypassword',
    );

    if ($shoutcast->source_connected) {
        my @listeners = $shoutcast->listeners;

        for my $listener (@listeners) {
            printf "Listener from %s, listening for %s",
                $listener->host, $listener->listen_time
            ;
        }
    } else {
        print "No source is currently connected.";
    }


=head1 DESCRIPTION

Object representing a listener, returned by Net::Shoutcast::Admin


=head1 INTERFACE

=over 4

=item new

There's no reason to create instances of Net::Shoutcast::Admin::Listener
directly; Net::Shoutcast::Admin creates and returns instances for you.

Having said that:

  $song = Net::Shoutcast::Admin::Listener->new( %params );

Creates a new Net::Shoutcast::Admin::Listener object.  Takes a hash of options
as follows:

=over 4

=item I

The host from which this listener is connected

=item I

The number of seconds this listener has been connected

=item I

The number of buffer underruns this listener has suffered

=item I

The software this user is reportedly using to listen

=back

=cut

sub new {

    my ($class, %params) = @_;
    my $self = bless {}, $class;

    $self->{last_update} = 0;

    my %acceptable_params = map { $_ => 1 }
        qw(host connect_time underruns agent);

    # make sure we haven't been given any bogus parameters:
    if (my @bad_params = grep { ! $acceptable_params{$_} } keys %params) {
        carp "Net::Shoutcast::Admin::Listener does not recognise param(s) "
            . join ',', @bad_params;
        return;
    }

    $self->{$_} = $params{$_} for keys %acceptable_params;

    if (my @missing_params = grep { ! $self->{$_} } keys %acceptable_params) {
        carp "Net::Shoutcast::Admin::Listener->new() must be supplied with "
        . "params: "
            . join ',', @missing_params;
        return;
    }

    return $self;

}


=item host

Returns the hostname this listener is connected from

=cut

sub host { return shift->{host} }


=item listen_time

Returns the number of seconds this listener has been connected

=cut

sub listen_time { return shift->{connect_time} }



=item underruns

Returns the number of buffer underruns this listener has suffered

=cut

sub underruns { return shift->{underruns} }


=item agent

Returns the agent this listener is reportedly using

=cut

sub agent { return shift->{agent} }


1; # Magic true value required at end of module
__END__