NAME

Audio::XMMSClient::Result - Results of Audio::XMMSClient operations

SYNOPSIS

  use Audio::XMMSClient;

  my $conn = Audio::XMMSClient->new($client_name);
  $conn->connect or die $c->get_last_error;

  my $result = $c->playback_status;
  $result->wait;
  print $result->value;

DESCRIPTION

This module provides an abstract, asyncronous interface to for retrieving results of Audio::XMMSClient server operations.

METHODS

get_class

Arguments: none

Return Value: $class

  my $class = $result->get_class;

Get the class of the result. This may be one of "default", "signal" and "broadcast".

disconnect

Arguments: none

Return Value: none

  $result->disconnect;

Disconnect a signal or a broadcast.

restart

Arguments: none

Return Value: none

  $result->restart;

Restart a signal.

A lot of signals you would like to get notified about when they change, instead of polling the server all the time. These results are "restartable".

  sub handler {
          my ($result) = @_;

          if ($result->iserror) {
                  warn "error: ", $result->get_error;
                  return;
          }

          my $id = $result->value;
          $result->restart;

          print "current id is: ${id}\n";
  }

  # connect, blah, blah, ...
  my $res = $conn->signal_playback_playtime;
  $res->notifier_set(\&handler);

In the above example the handler would be called when the playtime is updated. Only signals are restatable. Broadcasts will automaticly restart.

notifier_set

Arguments: \&func, $data?

Return Value: none

  $result->notifier_set(sub { die 'got an answer!' });

Set up a callback for the result retrival. This callback will be called when the answers arrives. It's arguments will be the result itself as well as an optional userdata if $data is passed.

wait

Arguments: none

Return Value: $result

  my $value = $result->wait->value;

Block for the reply. In a synchronous application this can be used to wait for the result. Will return the $result this method was called when the server replyed.

source_preference_set

Arguments: @preferences

Return Value: none

  $result->source_preference_set(qw{plugin/* plugin/id3v2 client/* server});

Set source @preferences to be used when fetching stuff from a propdict.

get_type

Arguments: none

Return Value: $type

  my $type = $result->get_type;

Get the type of the result. May be one of "none", "uint", "int", "dict", "bin", "coll", "list" or "propdict".

iserror

Arguments: none

Return Value: 1 | 0

  my $has_error = $result->iserror;

Check if the result represents an error. Returns a true value if the result is an error, false otherwise.

get_error

Arguments: none

Return Value: $message

  my $message = $result->get_error;

Get an error $message describing the error that occoured.

value

Arguments: none

Return Value: $scalar | \@arrayref | \%hashref | \%propdict

  my $value = $result->value;

Gets the return value of the $result. Depending of the results type ("get_type") you might get other types of return values.

decode_url

Arguments: $string

Return Value: $decoded_url

  my $decoded_url = $result->decode_url($url);
  my $decoded_url = Audio::XMMSClient::Result->decode_url($url);

Decode an URL-encoded $string.

Some strings (currently only the url of media) has no known encoding, and must be encoded in an UTF-8 clean way. This is done similar to the url encoding web browsers do. This functions decodes a string encoded in that way. OBSERVE that the decoded string HAS NO KNOWN ENCODING and you cannot display it on screen in a 100% guaranteed correct way (a good heuristic is to try to validate the decoded string as UTF-8, and if it validates assume that it is an UTF-8 encoded string, and otherwise fall back to some other encoding).

Do not use this function if you don't understand the implications. The best thing is not to try to display the url at all.

Note that the fact that the string has NO KNOWN ENCODING and CAN NOT BE DISPLAYED does not stop you from open the file if it is a local file (if it starts with "file://").

This method can either be called as a class or instance method.

AUTHOR

Florian Ragwitz <rafl@debian.org>

SEE ALSO

Audio::XMMSClient, Audio::XMMSClient::Result::PropDict

COPYRIGHT AND LICENSE

Copyright (C) 2006-2007, Florian Ragwitz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Audio::XMMSClient

perl -MCPAN -e shell
install Audio::XMMSClient