WWW::Grooveshark::Response - Grooveshark API response message
This document describes WWW::Grooveshark::Response version 0.01 (July 7, 2009).
WWW::Grooveshark::Response
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/>.
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 } }
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.
bless
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.
use WWW::Grooveshark::Response qw(:fault)
fault_code
If you need to "manually" craft an object of this class, this is how.
Builds a WWW::Grooveshark::Response object from the given hashref or hash.
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.
$response->result('key')
$response->{result}->{key}
AUTOLOAD
$response->key
songs
is_fault
The following methods exist for all class instances:
Returns the header element corresponding to $KEY.
Returns the ID of the session that created this response object. This is a shortcut for $response->header('sessionID').
$response->header('sessionID')
Checks whether this response object represents a fault.
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.
scalar
Returns the fault element corresponding to $KEY. This will only give a meaningful result if is_fault is true.
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).
$response->fault('code')
MALFORMED_REQUEST_FAULT
Some part of the request, most likely the parameters, was malformed.
NO_METHOD_FAULT
The requested method does not exist.
MISSING_OR_INVALID_PARAMETERS_FAULT
Method parameters were missing or incorrectly formatted.
SESSION_FAULT
Most likely the session has expired, or it failed to start.
AUTHENTICATION_FAULT
Authentication is required to access the invoked method.
AUTHENTICATION_FAILED_FAULT
The supplied user credentials were incorrect.
STREAM_FAULT
There was an error creating a stream key, or returning a stream server URL.
API_KEY_FAULT
The supplied API key is invalid, or is no longer active.
USER_BLOCKED_FAULT
A user's privacy restrictions have blocked access to their account through the API.
INTERNAL_FAULT
There was an error internal to the API while fulfilling the request.
SSL_FAULT
SSL is required to access the requested method.
ACCESS_RIGHTS_FAULT
Your API key does not have the proper access rights to invoke the requested method.
NO_RESOURCE_FAULT
Something doesn't exist, perhaps a userID, artistID, etc.
OFFLINE_FAULT
The requested method is offline and is temporarily unavailable.
Returns the contextually customized message of the fault represented by this response object. This is a shortcut for $response->fault('message').
$response->fault('message')
Returns the (possibly undefined) details of the fault represented by this response object. This is a shortcut for $response->fault('details').
$response->fault('details')
Returns an HTTP style status line, containing the fault code and message.
WWW::Grooveshark
Please report them! Create an issue at http://elementsofpuzzle.googlecode.com/ or drop me an e-mail.
Miorel-Lucian Palii <mlpalii@gmail.com>
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.
To install WWW::Grooveshark, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Grooveshark
CPAN shell
perl -MCPAN -e shell install WWW::Grooveshark
For more information on module installation, please visit the detailed CPAN module installation guide.