The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebService-Gravatar-0.11
River stage zero No dependents
1 ++
/ WebService::Gravatar

NAME

WebService::Gravatar - Perl interface to Gravatar API

VERSION

Version 0.11

SYNOPSIS

WebService::Gravatar provides an interface to Gravatar XML-RPC API.

    use WebService::Gravatar;
    use MIME::Base64;

    # Create a new instance of WebService::Gravatar
    my $grav = WebService::Gravatar->new(email => 'your@email.address',
                                         apikey => 'your_API_key');

    # Get a list of addresses
    my $addresses = $grav->addresses;

    if (defined $addresses) {
        # Print the userimage URL for each e-mail address
        foreach my $email (keys %$addresses) {
            print $addresses->{$email}->{'userimage_url'} . "\n";
        }
    }
    else {
        # We have a problem
        print STDERR "Error: " . $grav->errstr . "\n";
    }

    # Read image file data
    my $data;
    {
        local $/ = undef;
        open(F, "< my_pretty_face.png");
        $data = <F>;
        close(F);
    }
    
    # Save the image as a new userimage
    $grav->save_data(data => encode_base64($data), rating => 0);

    ...

DESCRIPTION

WebService::Gravatar is a Perl interface to Gravatar API. It aims at providing a close representation of the basic XML-RPC API, as documented on Gravatar website: http://en.gravatar.com/site/implement/xmlrpc/. All the method names, parameter names, and data structures are the same as in the API -- the only exception is that in the API the methods are named with camelCase, while the module uses lowercase_with_infix_underscores.

METHODS

All the instance methods return undef on failure. More detailed error information can be obtained by calling "err" and "errstr".

new

Creates a new instance of WebService::Gravatar.

    my $grav = WebService::Gravatar->new(email => 'your@email.address',
                                         apikey => 'your_API_key');

Parameters:

  • email

    (Required) E-mail address.

  • apikey

    (Required) API key. Can be ommitted if password is defined.

  • password

    (Required) Account password. Can be ommitted if apikey is defined.

exists

Checks whether a hash has a gravatar.

    $result = $grav->exists(hashes => ['e52beb5a6966554a02a56072cafebabe',
        '62345cdd79773f62a87fcbc6abadbabe'])

Parameters:

  • hashes

    (Required) An array of email hashes to check.

Returns: A reference to a hash that maps email hashes to statuses. Example:

    $result = {
        'e52beb5a6966554a02a56072cafebabe' => '1',
        '62345cdd79773f62a87fcbc6abadbabe' => '0'
    };

addresses

Gets a list of addresses for this account.

    $addresses = $grav->addresses;

Returns: A reference to a hash that maps addresses to userimage data. Example:

    $addresses = {
        'some@email.address' => {
            'rating' => '0',
            'userimage' => '8bfc8da2562a53ddd7e630a68badf00d',
            'userimage_url' => 'http://en.gravatar.com/userimage/123456/8bfc8da2562a53ddd7e630a68badf00d.jpg'
        },
        'another@email.address' => {
            'rating' => '1',
            'userimage' => '90f269fe7b67d0ce49f96427deadbabe',
            'userimage_url' => 'http://en.gravatar.com/userimage/123456/90f269fe7b67d0ce49f96427deadbabe.jpg'
        }
    };

userimages

Gets a list of userimages for this account.

    $userimages = $grav->userimages;

Returns: A reference to a hash that maps userimages to data. Example:

    $userimages = {
        '8bfc8da2562a53ddd7e630a68badf00d' => [
            '0',
            'http://en.gravatar.com/userimage/123456/8bfc8da2562a53ddd7e630a68badf00d.jpg'
        ],
        '90f269fe7b67d0ce49f96427deadbabe' => [
            '1',
            'http://en.gravatar.com/userimage/123456/90f269fe7b67d0ce49f96427deadbabe.jpg'
        ]
    };

save_data

Saves binary image data as a userimage for this account.

    $grav->save_data(data => $data, rating => 1);

Parameters:

  • data

    (Required) A base64 encoded image.

  • rating

    (Required) Rating.

Returns: Userimage string.

save_url

Reads an image via its URL and saves that as a userimage for this account.

    $grav->save_url(url => 'http://some.domain.com/image.png', rating => 0);

Parameters:

  • url

    (Required) A full URL to an image.

  • rating

    (Required) Rating.

Returns: Userimage string.

use_userimage

Uses the specified userimage as a gravatar for one or more addresses on this account.

    $grav->use_userimage(userimage => '9116aa83a568563290a681df61c0ffee'.
        addresses => ['some@email.address', 'another@email.address']);

Parameters:

  • userimage

    (Required) The userimage to be used.

  • addresses

    (Required) An array of email addresses for which this userimage will be used.

Returns: 1 on success, undef on failure.

remove_image

Removes the userimage associated with one or more email addresses.

    $result = $grav->remove_image(addresses => ['some@email.address',
        'another@email.address'])

Parameters:

  • addresses

    (Required) An array of email addresses to remove userimages for.

Returns: A reference to a hash that maps email addresses to statuses. Example:

    result = {
        'some@email.address' => 1,
        'another@email.address' => 0
    };

delete_userimage

Removes a userimage from the account and any email addresses with which it is associated.

    $grav->delete_userimage(userimage => '292ed56ce849657d47b04105deadbeef');

Parameters:

  • userimage

    (Required) The userimage to be removed from the account.

Returns: 1 on success, undef on failure.

test

API test method.

    $result = $grav->test(param => 1);

Returns: A reference to a hash which represents the parameters passed to the test method.

err

Returns the numeric code of last error.

    $err_code = $grav->err;

errstr

Returns the human readable text for last error.

    $err_description = $grav->errstr;

AUTHOR

Michal Wojciechowski, <odyniec at cpan.org>

BUGS

Please report any bugs or feature requests to bug-webservice-gravatar at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Gravatar. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WebService::Gravatar

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2010 Michal Wojciechowski, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO