NAME

WWW::Grooveshark::Response - Grooveshark API response message

VERSION

This document describes WWW::Grooveshark::Response version 0.02 (July 22, 2009).

This module is distributed with WWW::Grooveshark and therefore takes its version from that module. The latest version of both components is hosted on Google Code as part of <http://elementsofpuzzle.googlecode.com/>. Significant changes are also contributed to CPAN: http://search.cpan.org/dist/WWW-Grooveshark/.

SYNOPSIS

Response objects are returned by the API methods of WWW::Grooveshark:

  # some code to prepare $gs
  
  my $response = $gs->search_songs(query => "The Beatles");
  
  if($response->is_fault) {
      print STDERR $response->fault_line;
  }
  else {
      for($response->songs) {
          # do something interesting
      }
  }

DESCRIPTION

WWW::Grooveshark::Response encapsulates a response message from the Grooveshark API. A response consists of a header (sessionID, hostname, etc.) and either a result (in the case of "success" responses) or a fault code and message (in case of errors).

Internally, this class is just a blessed decoding of the JSON response, so if you're too lazy or stubborn to familiarize yourself with this interface, you may access the data structure directly like any hashref.

EXPORTS

None by default. The ":fault" tag can bring the integer fault constants in your namespace with: use WWW::Grooveshark::Response qw(:fault). The constants are listed as part of the documentation of the fault_code method below.

CONSTRUCTOR

If you need to "manually" craft an object of this class, this is how.

WWW::Grooveshark::Response->new( \%OBJECT | %OBJECT )

Builds a WWW::Grooveshark::Response object from the given hashref or hash.

METHOD AUTOLOADING

More often than not, you will probably be accessing the result element of a response object. Because $response->result('key') is only marginally better than $response->{result}->{key}, this class uses AUTOLOADing to support the terser $response->key syntax, as with the songs "method" in the "SYNOPSIS". This will only work with success responses, so ask each object if it is_fault. If the result does not contain the given key, the usual unknown method handling mechanism will take over.

METHODS

The following methods exist for all class instances:

$response->header( $KEY )

Returns the header element corresponding to $KEY.

$response->sessionID( )

Returns the ID of the session that created this response object. This is a shortcut for $response->header('sessionID').

$response->is_fault( )

Checks whether this response object represents a fault.

$response->result( [ $KEY ] )

Returns the result element corresponding to $KEY, or the whole result part of the response if no $KEY is specified. This will probably only give a meaningful result if is_fault is false. In scalar context, this method will return references where applicable. In list context, it will dereference arrayrefs and hashrefs before returning them.

$response->fault( $KEY )

Returns the fault element corresponding to $KEY. This will only give a meaningful result if is_fault is true.

$response->fault_code( )

Returns the integer code of the fault represented by this response object. This is a shortcut for $response->fault('code'). Check Grooveshark's API for the most up-to-date information about fault codes. The standard set at the time of this writing is listed below, along with the corresponding names for the constants that may be exported by this module (in parentheses).

1 Malformed request (MALFORMED_REQUEST_FAULT)

Some part of the request, most likely the parameters, was malformed.

2 No method (NO_METHOD_FAULT)

The requested method does not exist.

4 Missing or invalid parameters (MISSING_OR_INVALID_PARAMETERS_FAULT)

Method parameters were missing or incorrectly formatted.

8 Session (SESSION_FAULT)

Most likely the session has expired, or it failed to start.

16 Authentication (AUTHENTICATION_FAULT)

Authentication is required to access the invoked method.

32 Authentication failed (AUTHENTICATION_FAILED_FAULT)

The supplied user credentials were incorrect.

64 Stream (STREAM_FAULT)

There was an error creating a stream key, or returning a stream server URL.

128 API key (API_KEY_FAULT)

The supplied API key is invalid, or is no longer active.

256 User blocked (USER_BLOCKED_FAULT)

A user's privacy restrictions have blocked access to their account through the API.

512 Internal (INTERNAL_FAULT)

There was an error internal to the API while fulfilling the request.

1024 SSL (SSL_FAULT)

SSL is required to access the requested method.

2048 Access rights (ACCESS_RIGHTS_FAULT)

Your API key does not have the proper access rights to invoke the requested method.

4096 No resource (NO_RESOURCE_FAULT)

Something doesn't exist, perhaps a userID, artistID, etc.

8192 Offline (OFFLINE_FAULT)

The requested method is offline and is temporarily unavailable.

$response->fault_message( )

Returns the contextually customized message of the fault represented by this response object. This is a shortcut for $response->fault('message').

$response->fault_details( )

Returns the (possibly undefined) details of the fault represented by this response object. This is a shortcut for $response->fault('details').

$response->fault_line( )

Returns an HTTP style status line, containing the fault code and message.

SEE ALSO

WWW::Grooveshark

BUGS

Please report them! The preferred way to submit a bug report for this module is through CPAN's bug tracker: http://rt.cpan.org/Public/Dist/Display.html?Name=WWW-Grooveshark. You may also create an issue at http://elementsofpuzzle.googlecode.com/ or drop me an e-mail.

AUTHOR

Miorel-Lucian Palii <mlpalii@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Miorel-Lucian Palii

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. See perlartistic.