view release on metacpan or  search on metacpan

lib/Net/LastFM/Submission.pm  view on Meta::CPAN

The artist name. Required.

=item * I<title>

The track name. Required.

=item * I<time>

The time the track started playing, in UNIX timestamp format. Optional.
Default value is current time.

=item * I<source>

The source of the track. Optional.
Default value is B<R>.

=item * I<rating>

A single character denoting the rating of the track. Empty if not applicable. 

=item * I<length>

The length of the track in seconds. Required when the source is P, optional otherwise.

=item * I<album>

The album title, or an empty string if not known.

=item * I<id>

The position of the track on the album, or an empty string if not known.

=item * I<mb_id>

The MusicBrainz Track ID, or an empty string if not known.

=item * I<enc>

The encoding of the data, the module tries to encode the data (artist/title/album) unless the data is UTF-8. Optional.

=back

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
    }

=head1 FUNCTIONS

=head2 encode_data($data, $enc)

Function tries encode $data from $enc to UTF-8 and remove BOM-symbol. See L<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.

=head1 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.

=over 3

=item * I<_request_handshake()>

Generate I<GET> request for handshake. See I<handshake()> method.

=item * I<_request_now_playing(I<%args>)>

Generate I<POST> request for now playing. See I<now_playing(%args)> method.

=item * I<_request_submit(I<%args>)>

Generate I<POST> request for submit. See I<submit(%args)> method.

=back

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

I<_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 L<POE>, L<IO::Lambda> or L<AnyEvent>.

See L<POE::Component::Net::Submission::LastFM>.


=head1 DEBUG MODE

The module supports debug mode.

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

=head1 EXAMPLES

See I<examples/*> in this distributive.


=head1 SEE ALSO

=over 3