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: * "nowarnings" - "WWW::Newzbin" "warn"s whenever something unexpected happens (for example, if an unrecognised parameter is passed to a method, or if a recognised parameter is passed in an incorrect manner). Any true value (e.g. 1) for "nowarnings" disables all warnings issued by "WWW::Newzbin". * "proxy" - Defines a proxy server that the underlying LWP::UserAgent object will use when accessing Newzbin. Should be given in the format "http://proxy.address:port". "die"s if the username or password are missing, and "warn"s 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: * "query" (required) - The string of text to search for. * "category" - The Newzbin category (or categories) to search. Any of the "NEWZBIN_CAT_*" constants specified in WWW::Newzbin::Constants are valid. May be a single constant if only one category is to be searched, or an arrayref of constants if more than one category is to be searched. Default is none (i.e. all categories are searched). * "group" - The Usenet newsgroup (or newsgroups) to search. May be a scalar containing the name of a single newsgroup to search, or an arrayref of scalars if more than one newsgroup is to be searched. Default is none (i.e. all newsgroups are searched). * "retention" - The maximum age (in days) of a file that is permitted for it to be included as a search result. Must be at least 1, and at most 200 (this might change without notice; see "LIMITATIONS"). Default is currently 7 (again, this might change without notice; see "LIMITATIONS"). * "minsize" and "maxsize" - Respectively, the minimum and maximum sizes (in bytes) that files must be to count as results. Either parameter may be given; if both are given, "minsize" must be less than or equal to "maxsize", otherwise neither criteria will be considered in the search. Defaults are 0 for both parameters (i.e. no file size restrictions). * "filetype" - Filter by file type. At the time of writing, values currently accepted by Newzbin for this field are *SFV*, *NFO* and *NZB* (this might change without notice; see "LIMITATIONS"). Default is none (i.e. all file types are allowed). * "resultoffset" and "resultlimit" - Respectively, the offset at which to begin returning results and the maximum number of results to return for this search. Either parameter (or both) may be specified. "resultoffset" should be at least 0 and "resultlimit" must be at most 5000 (this might change without notice; see "LIMITATIONS"), otherwise neither criteria will be considered in the search. Defaults are 0 for "resultoffset" and 500 for "resultlimit" (again, this might change without notice; see "LIMITATIONS"). * "sortfield" and "sortorder" - Respectively, the field by which to sort and the order in which to sort. Any of the "NEWZBIN_SORTFIELD_*" constants specified in WWW::Newzbin::Constants are valid for the "sortfield" parameter, and any of the "NEWZBIN_SORTORDER_*" constants specified in WWW::Newzbin::Constants are valid for the "sortorder" parameter. If an invalid value is used for either parameter, the values given for both parameters will not be considered as search criteria. Defaults are "NEWZBIN_SORTFIELD_DATE" (the file's posted date) for "sortfield" and "NEWZBIN_SORTORDER_ASC" (ascending) for "sortorder" (either of these might change without notice; see "LIMITATIONS"). 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: * "fileid" - Newzbin's unique, internal ID for this file. Suitable for use in "get_nzb". * "subject" - The file's subject (title), as given by its poster. * "posttime" - Unix representation of the date and time at which the file was posted to Usenet (may not be completely accurate; see "LIMITATIONS"). * "filesize" - The size of the file, in bytes (may not be completely accurate; see "LIMITATIONS"). * "author" - The name of the user who posted the file to Usenet. * "groups" - A hashref containing a list of the newsgroups to which this file was posted. The method "die"s if required parameters were not passed to it, and "warn"s 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: * -1 - The search could not be carried out due to a technical fault; "error_message" gives a more verbose reason. * -2 - Invalid Newzbin account credentials were given in the constructor for "WWW::Newzbin". * -3 - The account credentials given in the constructor were valid, but the account is not a Newzbin Premium account. A Premium account is required for searching. * -4 - No results that matched the given search criteria could be found. 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: * "reportid" - A scalar containing the ID of the Newzbin report to download. All files listed in the report will be included in the NZB. * "fileid" - A scalar or arrayref of scalars containing the Newzbin file ID or IDs to include in the NZB. Other acceptable parameters for this method are as follows (all parameters listed below are optional): * "nogzip" - If set to a true value (i.e. 1), forcefully disables the compression feature explained above. Use this if Compress::Zlib is installed but isn't working for some reason. * "leavegzipped" - If set to a true value (i.e. 1), download the compressed version of the NZB file, but leave it compressed when the method returns (rather than decompressing it and returning that, which is the default behaviour). Useful if the NZB file needs to be transferred over a network to another end-user. The method's return value depends on how it was called: * If "fileid" was supplied, the method returns a scalar containing the NZB file. * If "reportid" was supplied, the method returns an array containing the following (in this order): * A scalar containing the NZB file; * A scalar containing the name of the report; * The Newzbin category in which the report was filed (see WWW::Newzbin::Constants). The method "die"s if one of the required parameters were not passed to it, and "warn"s 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: * Any integer greater than 0 - Newzbin rate-limits the number of NZB download requests that a user can make in a given timeframe. A positive integer means your account is being rate-limited and that you must wait this many seconds before sending your request again. See "LIMITATIONS". * -1 - The download could not be requested due to a technical fault; "error_message" gives a more verbose reason. * -2 - Invalid Newzbin account credentials were given in the constructor for "WWW::Newzbin". * -3 - The account credentials given in the constructor were valid, but the account is not a Newzbin Premium account. A Premium account is required for downloading NZB files. * -4 - In the words of Newzbin's documentation: *"the data trying to be fetched does not exist or is not accessible"*. If this error code is returned, do not try the same request again because you will receive the same response. * -5 - "WWW::Newzbin" downloaded the compressed version of the NZB and tried to decompress it using Compress::Zlib, but failed for some reason. If this error code is returned, consider using "nogzip" or "leavegzipped" to bypass decompression. 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 200 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 200, 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"). - Newzbin documentation for *FileFind*, which powers the "search_files" method. - Newzbin documentation for *DirectNZB*, which powers the "get_nzb" method. AUTHOR Chris Novakovic COPYRIGHT Copyright 2007 Chris Novakovic. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.