WebService-Pandora/lib/WebService/Pandora/Partner.pod
=head1 NAME
WebService::Pandora::Partner - Pandora WebService API Partner
=head1 SYNOPSIS
# creating a new Partner object
package WebService::Pandora::Partner::MyPartner;
use base 'WebService::Pandora::Partner';
sub new {
my $caller = shift;
my $class = ref( $caller );
$class = $caller if ( !$class );
my $self = $class->SUPER::new( username => 'username',
password => 'password',
deviceModel => 'model',
decryption_key => 'key',
encryption_key => 'key',
host => 'tuner.pandora.com' );
return $self;
}
# using a partner object
$partner = WebService::Pandora::Partner::MyPartner->new();
$result = $partner->login() or die( $partner->error() );
=head1 DESCRIPTION
This module is a base class that should be inherited and not used directly.
When logging in to the Pandora API, you must first login using a particular
partner, such as an Apple iOS or Android device. Each partner has its own
credentials and encryption/decryption keys, and some use different HTTP hosts
than others to query the API. The B<WebService::Pandora> package provides
modules for several known partners and will default to using
B<WebService::Pandora::Partner::iOS> if one isn't provided.
=head1 CONSTRUCTOR
=head2 new
Creates a new B<WebService::Pandora::Partner> object with the arguments given.
All of the options are required and used by the B<login()> method.
=over 4
=item username =E<gt> STRING [required]
The username of the partner to use when logging in.
=item password =E<gt> STRING [required]
The password of the partner to use when logging in.
=item deviceModel =E<gt> STRING [required]
The device model name to use when logging in.
=item encryption_key =E<gt> STRING [required]
The encryption key to use when encrypting the JSON data being sent to the
Pandora API method.
=item decryption_key =E<gt> STRING [required]
The decryption key to use when decrypting the JSON data send back from the
Pandora API method.
=item host =E<gt> STRING [required]
The host portion of the URL to use when issuing the HTTP request to the
Pandora API method.
=back
=head1 METHODS
=head2 login
Returns a hashref containing the information from the login request when the
login was successful, or a false value on failure. Internally, this will
execute the B<auth.partnerLogin> Pandora API method using the
B<WebService::Pandora::Method> library.
$result = $partner->login() or die( $partner->error() );
=head2 error
Returns a string containing a message about why the login call failed. The error string may
come from internally in the module, from a failed HTTP request, or from the Pandora API itself.
=head1 SEE ALSO
L<WebService::Pandora>
L<WebService::Pandora::Method>
=head1 AUTHOR
Mitch McCracken E<lt>mrmccrac@gmail.comE<gt>
=cut