/ 
WebService-Pandora-0.3
River stage zero No dependents
/ WebService::Pandora::Method

NAME

WebService::Pandora::Method - Pandora WebService API Method

SYNOPSIS

use WebService::Pandora::Method;

$method = WebService::Pandora::Method->new( name => 'methodName',
                                            partnerAuthToken => 'token',
                                            userAuthToken => 'token',
                                            partnerId => 'id',
                                            userId => 'id',
                                            syncTime => 1356998400,
                                            host => 'tuner.pandora.com',
                                            ssl => 1,
                                            encrypt => 1,
                                            cryptor => WebService::Pandora::Cryptor::iOS->new(),
                                            timeout => 10,
                                            params => {'param1' => 'val1',
                                                       'param2' => 'val2'} );

$result = $method->execute() or die( $method->error() );

DESCRIPTION

WebService::Pandora::Method is a module which queries the Pandora JSON API using the LWP::UserAgent and HTTP::Request libraries. It is used by the main WebService::Pandora module for all of the webservice methods it exposes. It handles all of the encryption, decryption, JSON conversion, and the Pandora API oddities for you.

CONSTRUCTOR

new

Creates a new WebService::Pandora::Method object with the arguments given. The method can then be execute()ed, returning a decrypted hashref representation of the JSON string returned by the Pandora API method.

$method = WebService::Pandora::Method->new( name => 'methodName',
                                            partnerAuthToken => 'token',
                                            userAuthToken => 'token',
                                            partnerId => 'id',
                                            userId => 'id',
                                            syncTime => 1356998400,
                                            host => 'tuner.pandora.com',
                                            ssl => 1,
                                            encrypt => 1,
                                            cryptor => WebService::Pandora::Cryptor::iOS->new(),
                                            timeout => 10,
                                            params => {'param1' => 'val1',
                                                       'param2' => 'val2'} );
name => STRING [required]

The name of the Pandora API method to call.

partnerAuthToken STRING [optional]

The partner authentication token to use. This is returned by the auth.partnerLogin API method and needed for some of the subsequent method calls.

userAuthToken STRING [optional]

The user authentication token to use. This is returned by the auth.userLogin API method and needed for some of the subsequent method calls.

partnerId STRING [optional]

The partner id to use. This is returned by the auth.partnerLogin API method and needed for some of the subsequent method calls.

userId STRING [optional]

The user id to use. This is returned by the auth.userLogin API method and needed for some of the subsequent method calls.

syncTime INTEGER [optional]

The unix epoch timestamp from when we logged in to the Pandora API. This is returned by the auth.partnerLogin API method and needed for some of the subsequent method calls.

host STRING [required]

The host portion of the URL where the Pandora JSON API is located. This is typically either tuner.pandora.com or internal-tuner.pandora.com.

ssl BOOLEAN [optional]

Whether or not to use HTTP or HTTPS when executing the method. Defaults to false (HTTP). Some of the Pandora API methods require HTTP, and others require HTTPS, so its important to specify the correct option depending upon which method.

encrypt BOOLEAN [optional]

Whether or not to encrypt the JSON data being sent using the WebService::Pandora::Cryptor object given via the cryptor argument. Defaults to true, as most Pandora API methods require it.

cryptor WebService::Pandora::Cryptor [optional]

The cryptor object to use to encrypt the JSON data when the encrypt option is given a true value.

timeout INTEGER [optional]

The timeout, in seconds, to pass to the underlying LWP::UserAgent object when the method is execute()ed. Defaults to 10.

params HASHREF [optional]

Any additional name => value pairs of parameters to pass to the method being executed. Many of the Pandora API methods require parameters to be given, so its important to specify the correct ones.

METHODS

execute

Returns either a JSON-decrypted hashref of the result from the Pandora API method call, or a true or false value to indicate success or failure. Use the error() method to find out why the method call failed. Internally, it will use LWP::UserAgent to send a crafted HTTP::Request based upon all the arguments provided to the constructor.

error

Returns a string containing a message about why the method call failed. The error string may come from internally in the module, from a failed HTTP request, or from the Pandora API itself.

SEE ALSO

WebService::Pandora WebService::Pandora::Cryptor LWP::UserAgent HTTP::Request JSON

AUTHOR

Mitch McCracken <mrmccrac@gmail.com>