Chris Novakovic > WWW-Newzbin > WWW::Newzbin

Download:
WWW/Newzbin/WWW-Newzbin-0.07.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.07   Source  

NAME ^

WWW::Newzbin - Interface to Newzbin.com's Usenet index

SYNOPSIS ^

        use WWW::Newzbin;
        use WWW::Newzbin::Constants qw(:all);
        
        my $nzb = WWW::Newzbin->new(
                username => "joebloggs",
                password => "secretpass123"
        );

        $nzb->lwp_useragent->timeout(10); # ADVANCED: allow less time for responses from newzbin
        
        my @results = $nzb->search_files(
                query => "the john smith orchestra",
                category => [ NEWZBIN_CAT_MUSIC, NEWZBIN_CAT_MOVIES ], # search in Newzbin's "music" and "movies" categories...
                group => [ "alt.binaries.music", "alt.binaries.test" ], # ...and return results from these groups only
                retention => 30, # no more than 30 days old
                resultlimit => 50, # return maximum of 50 results
                sortfield => NEWZBIN_SORTFIELD_SUBJECT, # sort by subject...
                sortorder => NEWZBIN_SORTORDER_ASC # ...in ascending order
        );
        
        if ($nzb->error_code) {
                print "Error # " . $nzb->error_code . ": " . $nzb->error_message;
        } else {
                print "Total number of results found: " . $nzb->search_files_total;
                print "Subject of result #1: " . $results[0]->{subject};
        }
        
        # make an nzb file for binaries in newzbin report #12345678
        my ($nzb_file, $report_name, $report_category) = $nzb->get_nzb(reportid => 12345678);
        
        # make an nzb file for binaries in newzbin report #12345678, and leave the nzb file gzip-compressed
        my ($nzb_file_gzipped, $report_name, $report_category) = $nzb->get_nzb(
                reportid => 12345678,
                leavegzip => 1
        );
        
        # make an nzb file for binaries with the newzbin file ids #123, #456 and #789, and don't compress it when downloading it
        my $nzb_file = $nzb->get_nzb(
                fileid => [ 123, 456, 789 ],
                nogzip => 1
        );

DESCRIPTION ^

This module is a Perl interface to the Newzbin.com v3 direct APIs. Newzbin is a Usenet binary indexing service that also offers .nzb files - short summary files containing all the information a newsreader requires to download any given binary or set of binaries from Usenet.

METHODS ^

COMMON METHODS

new

        my $nzb = WWW::Newzbin->new(
                username => "joebloggs",
                password => "secretpass123"
        );

The new() method constructs a new WWW::Newzbin object.

username and password should be valid Newzbin credentials, and both must be supplied for the object to be successfully constructed. The new() method does not check whether these credentials are valid.

Other (optional) parameters are:

dies if the username or password are missing, and warns if any unrecognised parameters are given.

error_code

        print "Error code for last error: " . $nzb->error_code;

If an error occurred during the last method call, this method will return an integer describing what kind of error occurred (or undef if an error did not occur during the last method call). Check the documentation for each individual method for a list of expected return values from error_code.

This method's output is programmatically useful, but isn't pretty to give back to a user. Consider "error_message" for user feedback.

error_message

        print "An error occurred while processing your request: " . $nzb->error_message;

If an error occurred during the last method call, this method will return a short description of the error (or undef if an error did not occur during the last method call). Check the documentation for each individual method for an idea of what to expect for a return value from this method - the message will depend on the "error_code".

This method's output is useful for user feedback, but isn't very useful programmatically. Consider "error_code" for handling errors using code.

search_files

        my @results = $nzb->search_files(
                query => "the john smith orchestra",
                category => [ NEWZBIN_CAT_MUSIC, NEWZBIN_CAT_MOVIES ],
                group => [ "alt.binaries.music", "alt.binaries.test" ],
                retention => 30,
                resultlimit => 50,
                sortfield => NEWZBIN_SORTFIELD_SUBJECT,
                sortorder => NEWZBIN_SORTORDER_ASC
        );

Searches Newzbin's files index for a given string, and (optionally) filters the results based on given criteria. Please note that it is not possible to search Newzbin without a valid Premium account.

Search criteria are passed as parameters to the method. The following parameters are allowed; each is optional unless otherwise specified:

If the search is successful, the method returns an array of results (with the first result at the head of the array). Each result is a hashref containing the following keys:

The method dies if required parameters were not passed to it, and warns if unrecognised parameters were passed (but the search will still progress). If the search was otherwise unsuccessful, the method returns undef and "error_code" will return one of the following values:

search_files_total

        print "Total number of files found: " . $nzb->search_files_total;

If used after a successful call to "search_files", this method returns the total number of results that would have been returned if resultlimit had not been specified. If used after an unsuccessful (or no) call to "search_files", returns undef.

get_nzb

        my ($nzb_file, $report_name, $report_category) = $nzb->get_nzb(reportid => 12345678);
        
        my ($nzb_file_gzipped, $report_name, $report_category) = $nzb->get_nzb(
                reportid => 12345678,
                leavegzip => 1
        );
        
        my $nzb_file = $nzb->get_nzb(
                fileid => [ 123, 456, 789 ]
        );

Constructs an NZB (.nzb file) based on either a Newzbin report ID or one or more Newzbin file IDs. Please note that it is not possible to construct NZB files without a valid Premium account.

NZB files are easily compressed, and Newzbin supports gzip file compression for NZB downloads. If Compress::Zlib is available, WWW::Newzbin will transparently handle compression to reduce bandwidth usage; otherwise, the NZB file will be downloaded uncompressed.

Either (but not both) of the following parameters are required:

Other acceptable parameters for this method are as follows (all parameters listed below are optional):

The method's return value depends on how it was called:

The method dies if one of the required parameters were not passed to it, and warns if unrecognised parameters were passed (but the download will still occur). If the download was otherwise unsuccessful, the method returns undef and "error_code" will return one of the following values:

ADVANCED METHODS

lwp_useragent

        $nzb->lwp_useragent->timeout(30);

Grants access to the underlying LWP::UserAgent object that powers WWW::Newzbin. Useful for fine-tuning; if you just need to specify a proxy server for LWP::UserAgent, consider using the far-neater proxy parameter in the "new" constructor.

LIMITATIONS ^

USENET LIMITATIONS

The posttime and filesize values returned for each result by "search_files" may not always be accurate because Newzbin reports the post time and file size based on the first news server on which it sees the file. Newzbin's FileFind documentation states that the file size "should be accurate to within a few kilobytes", however.

NEWZBIN LIMITATIONS

FileFind, the Newzbin API upon which "search_files" relies, has default values for a number of its parameters (specifically: retention, resultoffset and resultlimit). The WWW::Newzbin documentation states these defaults but they are actually set by the Newzbin API, not by this module. This means, of course, that the Newzbin developers could change these default values at any time, which may drastically alter the search results that WWW::Newzbin returns. Every effort will be made to keep this documentation up-to-date with any changes made to the default values in the FileFind API, but you are advised to explicitly specify "search_files" parameters rather than relying too much on the defaults.

Newzbin's retention is currently 240 days. At the moment no mainstream Usenet provider has a retention that Newzbin doesn't cover, but this might change in future. Therefore, while the WWW::Newzbin documentation states that the "search_files" retention parameter must not exceed 240, this limit is not hardcoded and specifying longer retentions will not result in a warning or error.

Newzbin intentionally caps FileFind's result limit to 5000. The "search_files" resultlimit parameter, therefore, should not exceed 5000; although Newzbin could of course change or remove this limit at any time without notice, so WWW::Newzbin will not produce a warning or error if resultlimit is greater than 5000.

The "search_files" filetype parameter only accepts a handful of file types. Newzbin's FileFind documentation states that you're welcome to contact them to request indexing of other file types. Nevertheless, the FileFind documentation also states that file type filtering is "fairly accurate, but don't rely on it as any malicious Usenet poster could easily circumvent it".

DirectNZB, the Newzbin API upon which "get_nzb" relies, only allows either one report ID or several file IDs per request. The documentation states that this is unlikely to change in future.

DirectNZB also limits the rate at which accounts can generate NZB files - currently the restriction is 5 NZB files per minute per IP address. If "get_nzb" reports a positive integer as its error_code, you are advised to wait that many seconds (or, preferably, 60 seconds) before calling "get_nzb" again. Failure to do so might result in your IP address (or even the entire account) being banned from accessing Newzbin.

DEPENDENCIES ^

WWW::Newzbin::Constants, LWP::UserAgent

Optional: Compress::Zlib

SEE ALSO ^

Documentation for associated modules (see "DEPENDENCIES").

http://docs.newzbin.com/index.php/Newzbin:FileFind - Newzbin documentation for FileFind, which powers the "search_files" method.

http://docs.newzbin.com/index.php/Newzbin:DirectNZB - Newzbin documentation for DirectNZB, which powers the "get_nzb" method.

AUTHOR ^

Chris Novakovic <chrisn@cpan.org>

COPYRIGHT ^

Copyright 2007-8 Chris Novakovic.

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

syntax highlighting: