Ubuntu Manpage: POE::Component::Client::MPD - full-blown poe-aware mpd client library

Provided by: libpoe-component-client-mpd-perl_2.001-1_all

NAME

       POE::Component::Client::MPD - full-blown poe-aware mpd client library

VERSION

       version 2.001

SYNOPSIS

           use POE qw{ Component::Client::MPD };
           POE::Component::Client::MPD->spawn( {
               host           => 'localhost',
               port           => 6600,
               password       => 's3kr3t',  # mpd password
               alias          => 'mpd',     # poe alias
               status_msgs_to => 'myapp',   # session to send status info to
           } );

           # ... later on ...
           $_[KERNEL]->post( mpd => 'next' );

DESCRIPTION

       POCOCM gives a clear message-passing interface (sitting on top of POE) for talking to and
       controlling MPD (Music Player Daemon) servers. A connection to the MPD server is
       established as soon as a new POCOCM object is created.

       Commands are then sent to the server as messages are passed.

ATTRIBUTES

   host
       The hostname where MPD is running. Defaults to environment var "MPD_HOST", then to
       'localhost'. Note that "MPD_HOST" can be of the form "password@host:port" (each of
       "password@" or ":port" can be omitted).

   port
       The port that MPD server listens to. Defaults to environment var "MPD_PORT", then to
       parsed "MPD_HOST" (cf above), then to 6600.

   password
       The password to access special MPD functions. Defaults to environment var "MPD_PASSWORD",
       then to parsed "MPD_HOST" (cf above), then to empty string.

   alias
       A string to alias the newly created POE session. Defaults to "mpd".

   status_msgs_to
       A session (name or id) to whom to send connection status to. Optional, although
       recommended. No default. When this is done, pococm will send *additional* events to the
       session, such as: "mpd_connected" when pococm is connected, "mpd_disconnected" when pococm
       is disconnected, etc. You thus need to register some handlers for those events.

METHODS

   my $id = POE::Component::Client::MPD->spawn( \%params );
       This method will create a POE session responsible for communicating with mpd. It will
       return the poe id of the session newly created. You can tune it by passing some arguments
       as a hash reference. See the attributes for allowed values.

PUBLIC EVENTS ACCEPTED

   MPD-related events
       The goal of a POCOCM session is to drive a remote MPD server. This can be achieved by a
       lot of events. Due to their sheer number, they have been regrouped logically in modules.

       However, note that to use those events, you need to send them to the POCOCM session that
       you created with "spawn()" (see above). Indeed, the logical split is only internal: you
       are to use the same peer.

       For a list of public events that update and/or query MPD, see embedded pod in:

       •   POE::Component::Client::MPD::Commands for general commands

       •   POE::Component::Client::MPD::Playlist for playlist-related commands. Those events
           begin with "pl.".

       •   POE::Component::Client::MPD::Collection for collection- related commands. Those events
           begin with "coll.".

   disconnect( )
       Request the POCOCM to be shutdown. Leave mpd running. Generally sent when one wants to
       exit her program.

EVENTS FIRED

       A POCOCM session will fire events, either to answer an incoming event, or to inform about
       some changes regarding the remote MPD server.

   Answer events
       For each incoming event received by the POCOCM session, it will fire back one of the
       following answers:

       •   mpd_result( $msg, $answer )

           Indicates a success. $msg is a POE::Component::Client::MPD::Message object with the
           original request, to identify the issued command (see
           POE::Component::Client::MPD::Message pod for more information). Its "status()"
           attribute is true, further confirming success.

           $answer is what has been answered by the MPD server. Depending on the command, it can
           be either:

           •   "undef": commands "play", etc.

           •   an Audio::MPD::Common::Stats object: command "stats"

           •   an Audio::MPD::Common::Status object: command "status"

           •   an Audio::MPD::Common::Item object: commands "song", etc.

           •   an array reference: commands "coll.files", etc.

           •   etc.

           Refer to the documentation of each event to know what type of answer you can expect.

       •   mpd_error( $msg, $errstr )

           Indicates a failure. $msg is a POE::Component::Client::MPD::Message object with the
           original request, to identify the issued command (see
           POE::Component::Client::MPD::Message pod for more information). Its "status()"
           attribute is false, further confirming failure.

           $errstr is what the error message as returned been answered by the MPD server.

   Auto-generated events
       If you supplied the "status_msgs_to" attribute, the following events are fired to this
       peer by pococm:

       •   mpd_connect_error( $reason )

           Called when pococm-conn could not connect to a mpd server. It can be either retriable,
           or fatal. Check $reason for more information.

       •   mpd_connected( )

           Called when pococm-conn made sure we're talking to a mpd server.

       •   mpd_disconnected( )

           Called when pococm-conn has been disconnected from mpd server.

AUTHOR

       Jerome Quelin

COPYRIGHT AND LICENSE

       This software is copyright (c) 2007 by Jerome Quelin.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

PUBLIC EVENTS ACCEPTED

EVENTS FIRED

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE