lib/POE/Component/Client/MPD.pm

   1 #
   2 # This program is free software; you can redistribute it and/or modify
   3 # it under the terms of the GNU General Public License as published by
   4 # the Free Software Foundation; either version 2 of the License, or
   5 # (at your option) any later version.
   6 #
   7 # This program is distributed in the hope that it will be useful,
   8 # but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 # GNU General Public License for more details.
  11 #
  12 # You should have received a copy of the GNU General Public License
  13 # along with this program; if not, write to the Free Software
  14 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  15 #
  16 #
  17
  18 package POE::Component::Client::MPD;
  19
  20 use strict;
  21 use warnings;
  22
  23 use POE;
  24 use POE::Component::Client::MPD::Collection;
  25 use POE::Component::Client::MPD::Commands;
  26 use POE::Component::Client::MPD::Connection;
  27 use POE::Component::Client::MPD::Message;
  28 use POE::Component::Client::MPD::Playlist;
  29 use base qw[ Class::Accessor::Fast ];
  30 __PACKAGE__->mk_accessors( qw[ _host _password _port  _version ] );
  31
  32
  33 our $VERSION = '0.3.0';
  34
  35
  36 #
  37 # my $id = spawn( \%params )
  38 #
  39 # This method will create a POE session responsible for communicating
  40 # with mpd. It will return the poe id of the session newly created.
  41 #
  42 # You can tune the pococm by passing some arguments as a hash reference,
  43 # where the hash keys are:
  44 #   - host: the hostname of the mpd server. If none given, defaults to
  45 #     MPD_HOST env var. If this var isn't set, defaults to localhost.
  46 #   - port: the port of the mpd server. If none given, defaults to
  47 #     MPD_PORT env var. If this var isn't set, defaults to 6600.
  48 #   - password: the password to sent to mpd to authenticate the client.
  49 #     If none given, defaults to C<MPD_PASSWORD> env var. If this var
  50 #     isn't set, defaults to empty string.
  51 #   - alias: an optional string to alias the newly created POE session.
  52 #
  53 sub spawn {
  54     my ($type, $args) = @_;
  55
  56     my $collection = POE::Component::Client::MPD::Collection->new;
  57     my $commands   = POE::Component::Client::MPD::Commands->new;
  58     my $playlist   = POE::Component::Client::MPD::Playlist->new;
  59
  60     my $session = POE::Session->create(
  61         args          => [ $args ],
  62         inline_states => {
  63             # private events
  64             '_start'       => \&_onpriv_start,
  65             '_send'        => \&_onpriv_send,
  66             # protected events
  67             '_mpd_data'    => \&_onprot_mpd_data,
  68             '_mpd_error'   => \&_onprot_mpd_error,
  69             '_mpd_version' => \&_onprot_mpd_version,
  70             # public events
  71             'disconnect'   => \&_onpub_disconnect,
  72         },
  73         object_states => [
  74             $commands   => { # general purpose commands
  75                 'volume'           => '_onpub_volume',
  76                 'output_enable'    => '_onpub_output_enable',
  77                 'output_disable'   => '_onpub_output_disable',
  78
  79                 'stats'            => '_onpub_stats',
  80                 '_stats_postback'  => '_onpriv_stats_postback',
  81                 'status'           => '_onpub_status',
  82                 '_status_postback' => '_onpriv_status_postback',
  83
  84                 'next'             => '_onpub_next',
  85             },
  86             $collection => { # collection related commands
  87                 'coll.all_files'    => '_onpub_all_files',
  88             },
  89             $playlist   => { # playlist related commands
  90                 'pl.add'            => '_onpub_add',
  91                 'pl.delete'         => '_onpub_delete',
  92             },
  93         ],
  94     );
  95
  96     return $session->ID;
  97 }
  98
  99
 100 #--
 101 # public events
 102
 103 #
 104 # event: disconnect()
 105 #
 106 # Request the pococm to be shutdown. No argument.
 107 #
 108 sub _onpub_disconnect {
 109     my ($k,$h) = @_[KERNEL, HEAP];
 110     $k->alias_remove( $h->{alias} ) if defined $h->{alias}; # refcount--
 111     $k->post( $h->{_socket}, 'disconnect' );                # pococm-conn
 112 }
 113
 114
 115 #--
 116 # protected events.
 117
 118 #
 119 # Event: _mpd_data( $msg )
 120 #
 121 # Received when mpd finished to send back some data.
 122 #
 123 sub _onprot_mpd_data {
 124     my $msg = $_[ARG0];
 125     return if $msg->_answer == $DISCARD;
 126
 127     # check for post-callback.
 128     if ( defined $msg->_post ) {
 129         $_[KERNEL]->yield( $msg->_post, $msg ); # need a post-treatment...
 130         $msg->_post( undef );                   # remove postback.
 131         return;
 132     }
 133
 134     # send result.
 135     $_[KERNEL]->post( $msg->_from, 'mpd_result', $msg );
 136 }
 137
 138 sub _onprot_mpd_error {
 139     warn "mpd error\n";
 140 }
 141
 142
 143 #
 144 # Event: _mpd_version( $vers )
 145 #
 146 # Event received during connection, when mpd server sends its version.
 147 # Store it for later usage if needed.
 148 #
 149 sub _onprot_mpd_version {
 150     $_[HEAP]->{version} = $_[ARG0];
 151 }
 152
 153
 154 #--
 155 # private events
 156
 157 #
 158 # Event: _start( \%params )
 159 #
 160 # Called when the poe session gets initialized. Receive a reference
 161 # to %params, same as spawn() received.
 162 #
 163 sub _onpriv_start {
 164     my ($h, $args) = @_[HEAP, ARG0];
 165
 166     # set up connection details.
 167     $args = {} unless defined $args;
 168     my %params = (
 169         host     => $ENV{MPD_HOST}     || 'localhost',
 170         port     => $ENV{MPD_PORT}     || '6600',
 171         password => $ENV{MPD_PASSWORD} || '',
 172         %$args,                        # overwrite previous defaults
 173         id       => $_[SESSION]->ID,   # required for connection
 174     );
 175
 176     # set an alias (for easier communication) if requested.
 177     $h->{alias} = delete $params{alias};
 178     $_[KERNEL]->alias_set($h->{alias}) if defined $h->{alias};
 179
 180     $h->{password} = delete $params{password};
 181     $h->{_socket}  = POE::Component::Client::MPD::Connection->spawn(\%params);
 182 }
 183
 184
 185 =begin FIXME
 186
 187 #
 188 # _connected()
 189 #
 190 # received when the poe::component::client::tcp is (re-)connected to the
 191 # mpd server.
 192 #
 193 sub _connected {
 194     my ($self, $k) = @_[OBJECT, KERNEL];
 195     $k->post($_[HEAP]{_socket}, 'send', 'status' );
 196     # send password information
 197 }
 198
 199 =end FIXME
 200
 201 =cut
 202
 203
 204
 205 #
 206 # event: _send( $msg )
 207 #
 208 # Event received to request message sending over tcp to mpd server.
 209 # $msg is a pococm-message partially filled.
 210 #
 211 sub _onpriv_send {
 212     $_[KERNEL]->post( $_[HEAP]->{_socket}, 'send', $_[ARG0] );
 213 }
 214
 215
 216 1;
 217
 218 __END__
 219
 220
 221 =head1 NAME
 222
 223 POE::Component::Client::MPD - a full-blown mpd client library
 224
 225
 226 =head1 SYNOPSIS
 227
 228     use POE qw[ Component::Client::MPD ];
 229     POE::Component::Client::MPD->spawn( {
 230         host     => 'localhost',
 231         port     => 6600,
 232         password => 's3kr3t',  # mpd password
 233         alias    => 'mpd',     # poe alias
 234     } );
 235
 236     # ... later on ...
 237     $_[KERNEL]->post( 'mpd', 'next' );
 238
 239
 240 =head1 DESCRIPTION
 241
 242 POCOCM gives a clear message-passing interface (sitting on top of POE)
 243 for talking to and controlling MPD (Music Player Daemon) servers. A
 244 connection to the MPD server is established as soon as a new POCOCM
 245 object is created.
 246
 247 Commands are then sent to the server as messages are passed.
 248
 249
 250 =head1 PUBLIC PACKAGE METHODS
 251
 252 =head2 spawn( \%params )
 253
 254 This method will create a POE session responsible for communicating with mpd.
 255 It will return the poe id of the session newly created.
 256
 257 You can tune the pococm by passing some arguments as a hash reference, where
 258 the hash keys are:
 259
 260 =over 4
 261
 262 =item * host
 263
 264 The hostname of the mpd server. If none given, defaults to C<MPD_HOST>
 265 environment variable. If this var isn't set, defaults to C<localhost>.
 266
 267
 268 =item * port
 269
 270 The port of the mpd server. If none given, defaults to C<MPD_PORT>
 271 environment variable. If this var isn't set, defaults to C<6600>.
 272
 273
 274 =item * password
 275
 276 The password to sent to mpd to authenticate the client. If none given, defaults
 277 to C<MPD_PASSWORD> environment variable. If this var isn't set, defaults to C<>.
 278
 279
 280 =item * alias
 281
 282 An optional string to alias the newly created POE session.
 283
 284
 285 =back
 286
 287
 288 =head1 PUBLIC EVENTS
 289
 290 For a list of public events that you can send to a POCOCM session, check:
 291
 292 =over 4
 293
 294 =item *
 295
 296 C<POCOCM::Commands> for general commands
 297
 298 =item *
 299
 300 C<POCOCM::Playlist> for playlist-related commands
 301
 302 =item *
 303
 304 C<POCOCM::Collection> for collection-related commands
 305
 306 =back
 307
 308
 309 =head1 BUGS
 310
 311 Please report any bugs or feature requests to C<bug-poe-component-client-mpd at
 312 rt.cpan.org>, or through the web interface at
 313 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-Client-MPD>.
 314 I will be notified, and then you'll automatically be notified of progress on
 315 your bug as I make changes.
 316
 317
 318 =head1 SEE ALSO
 319
 320 You can find more information on the mpd project on its homepage at
 321 L<http://www.musicpd.org>, or its wiki L<http://mpd.wikia.com>.
 322
 323 C<POE::Component::Client::MPD development> takes place on C<< <audio-mpd
 324 at googlegroups.com> >>: feel free to join us. (use
 325 L<http://groups.google.com/group/audio-mpd> to sign in). Our subversion
 326 repository is located at L<https://svn.musicpd.org>.
 327
 328
 329 You can also look for information on this module at:
 330
 331 =over 4
 332
 333 =item * AnnoCPAN: Annotated CPAN documentation
 334
 335 L<http://annocpan.org/dist/POE-Component-Client-MPD>
 336
 337 =item * CPAN Ratings
 338
 339 L<http://cpanratings.perl.org/d/POE-Component-Client-MPD>
 340
 341 =item * RT: CPAN's request tracker
 342
 343 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-Client-MPD>
 344
 345 =back
 346
 347
 348 =head1 AUTHOR
 349
 350 Jerome Quelin, C<< <jquelin at cpan.org> >>
 351
 352
 353 =head1 COPYRIGHT & LICENSE
 354
 355 Copyright 2007 Jerome Quelin, all rights reserved.
 356
 357 This program is free software; you can redistribute it and/or modify
 358 it under the terms of the GNU General Public License as published by
 359 the Free Software Foundation; either version 2 of the License, or
 360 (at your option) any later version.
 361
 362 This program is distributed in the hope that it will be useful,
 363 but WITHOUT ANY WARRANTY; without even the implied warranty of
 364 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 365 GNU General Public License for more details.
 366
 367 You should have received a copy of the GNU General Public License
 368 along with this program; if not, write to the Free Software
 369 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 370
 371 =cut