Анатолий Шарифулин > Net-LastFM-Submission-0.64 > Net::LastFM::Submission

Download:
Net-LastFM-Submission-0.64.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.64   Source  

NAME ^

Net::LastFM::Submission - Perl interface to the Last.fm Submissions Protocol

SYNOPSIS ^

    use Net::LastFM::Submission;
    
    my $submit = Net::LastFM::Submission->new(
        user      => 'net_lastfm',
        password  => '12',
    );
    
    $submit->handshake;
    
    $submit->submit(
        artist => 'Artist name',
        title  => 'Track title',
        time   => time - 10*60, # 10 minutes ago
    );
    
    $submit->now_playing(
        artist => 'Artist name',
        title  => 'Track title',
    );

DESCRIPTION ^

The module provides a simple Perl interface to the Last.fm Submissions Protocol (current version is 1.2.1).

The Last.fm Submissions Protocol is designed for the submission of now-playing and recent historical track data to Last.fm user profiles (aka 'Scrobbling').

http://www.lastfm.ru/api/submissions

METHODS ^

new(%args)

This is a constructor for Net::LastFM::Submission object. It takes list of parameters or hashref parameter.

    # list
    my $submit = Net::LastFM::Submission->new(
        user     => 'net_lastfm',
        password => '12',
    );
    
    # hashref
    my $submit = Net::LastFM::Submission->new({
        user     => 'net_lastfm',
        password => '12',
    });

This is a list of support parameters:

handshake()

The initial negotiation with the submissions server to establish authentication and connection details for the session. See http://www.lastfm.ru/api/submissions#handshake.

    $submit->handshake;

If the handshake is successful, the returned hashref should be the following format:

    {
        'status' => 'OK',
        'sid'    => 'Session ID', # the scrobble session id
        'url'    => {
            'np'  => 'Now-Playing URL',
            'sm'  => 'Submission URL'
        }
    }

Else:

    {
        'error'  => 'BANNED/BADAUTH/BADTIME/FAILED',
        'code'   => '200/500', # code of status line response
        'reason' => '...'      # reason of error
    }

now_playing(%args)

Optional lightweight notification of now-playing data at the start of the track for realtime information purposes. See http://www.lastfm.ru/api/submissions#np.

It takes list of parameters or hashref parameter.

    # list
    $submit->now_playing(
        artist => 'Artist name',
        title  => 'Track title',
    );
    
    # hashref
    $submit->now_playing({
        artist => 'Artist name',
        title  => 'Track title',
    });

This is a list of support parameters:

If the notification is successful, the returned hashref should be the following format:

    {
        'status' => 'OK',
    }

Else:

    {
        'error'  => 'ERROR/BADSESSION',
        'code'   => '200/500', # code of status line response
        'reason' => '...'      # reason of error
    }

submit(%args)

Submission of full track data at the end of the track for statistical purposes. See http://www.lastfm.ru/api/submissions#subs.

It takes list of parameters (information about one track) or list of hashref parameters (limit of Last.FM is 50).

    # list
    $submit->submit(
        artist => 'Artist name',
        title  => 'Track title',
    );
    
    # hashref
    $submit->submit(
        grep { $_->{'source'} = 'R' }
        {
            artist => 'Artist name 1',
            title  => 'Track title 1',
            time   => time - 10*60,
        },
        {
            artist => 'Artist name 2',
            title  => 'Track title 2',
        }
    );

This is a list of support parameters:

If the submit is successful, the returned hashref should be the following format:

    {
        'status' => 'OK',
    }

Else:

    {
        'error'  => 'ERROR/BADSESSION/FAILED',
        'code'   => '200/500', # code of status line response
        'reason' => '...'      # reason of error
    }

FUNCTIONS ^

encode_data($data, $enc)

Function tries encode $data from $enc to UTF-8 and remove BOM-symbol. See Encode.

    use Net::LastFM::Submission 'encode_data';
    
    encode_data('foo bar in cp1251', 'cp1251');

Encoding of all data for Last.fm must be UTF-8.

GENERATE REQUESTS AND PARSE RESPONSES ^

Module can generate a requests for handshake, now playing and submit operations. These methods return HTTP::Request instance. One request has support parameters same as method.

Also module can parse a response (HTTP::Response instance) of these requests.

_response($response)

        my $request  = $self->_request_handshake; # generate request for handshake, return HTTP::Request instance
        ...
        my $response = send_request($request); # send this request, return HTTP::Response instance
        ...
        $self->_response($response); # parse this request

This feature can use for async model (even-driven) such as POE, IO::Lambda or AnyEvent.

See POE::Component::Net::Submission::LastFM.

DEBUG MODE ^

The module supports debug mode.

    BEGIN { $ENV{SUBMISSION_DEBUG}++ };
    use Net::LastFM::Submission;

EXAMPLES ^

See examples/* in this distributive.

SEE ALSO ^

DEPENDENCIES ^

LWP::UserAgent HTTP::Request::Common Encode Digest::MD5 Carp Exporter

AUTHOR ^

Anatoly Sharifulin, <sharifulin at gmail.com>

BUGS ^

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

SUPPORT & DOCUMENTATION ^

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

    perldoc Net::LastFM::Submission

You can also look for information at:

COPYRIGHT & LICENSE ^

Copyright (C) 2009 Anatoly Sharifulin

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

syntax highlighting: