Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FreeDB(3)	      User Contributed Perl Documentation	     FreeDB(3)

NAME
       Net::FreeDB - Perl interface to freedb server(s)

SYNOPSIS
	   use Net::FreeDB;
	   $freedb = Net::FreeDB->new();
	   $discdata = $freedb->getdiscdata('/dev/cdrom');
	   my $cddb_file_object	= $freedb->read('rock',	$discdata->{ID});
	   print $cddb_file_object->id;

DESCRIPTION
	   Net::FreeDB was inspired by Net::CDDB.  And in-fact
	   was designed	as a replacement in-part by Net::CDDB's
	   author Jeremy D. Zawodny.  Net::FreeDB allows an
	   oop interface to the	freedb server(s) as well as
	   some	basic cdrom functionality like determining
	   disc	ids, track offsets, etc.

   METHODS
       new(remote_host => $h, remote_port => $p, user => $u, hostname => $hn,
       timeout => $to)
		Constructor:
		   Creates a new Net::FreeDB object.

		Parameters:
		     Set to username or	user-string you'd like to be logged as.	Defaults to $ENV{USER}

		   HOSTNAME: (optional)
		     Set to the	hostname you'd like to be known	as. Defaults to	$ENV{HOSTNAME}

		   TIMEOUT: (optional)
		     Set to the	number of seconds to timeout on	freedb server. Defaults	to 120

	       new() creates and returns a new Net::FreeDB object that is connected
	       to either the given host	or freedb.freedb.org as	default.

       lscat
	       Returns a list of all available categories on the server.
	       Sets $obj->error	on error

       query($id, $num_trks, $trk_offset1, $trk_offset2, $trk_offset3...)
	     Parameters:

	       query($$$...) takes:
	     1:	a discid
	     2:	the number of tracks
	     3:	first track offset
	     4:	second track offset... etc.

	       Query expects $num_trks number of extra params after the	first two.

	       query() returns an array	of hashes. The hashes looks like:

	       {
		   Category => 'newage',
		   DiscID   => 'discid',
		   Artist   => 'artist',
		   Album    => 'title'
	       }

	       Sets $obj->error	on error

	       NOTE: query() can return	'inexact' matches and/or 'multiple exact'
	       matches.	The returned array is the given	returned match(es).

       read($server_category_string, $disc_id)
	     Parameters:

	       read($$)	takes 2	parameters, the	first being a server category name.
	       This can	be any string either that you make up yourself or
	       that you	believe	the disc to be.	The second is the disc id. This
	       may be generated	for the	current	cd in your drive by calling get_local_disc_id()

	       Sets $obj->error	on error

	     NOTE:
	       Using an	incorrect category will	result in either no return or an
	       incorrect return. Please	check the CDDB::File documentation for
	       information on this module.

	     read() requests a freedb record for the given information and returns a
	       CDDB::File object.

       unlink($server_category_string, $disc_id)
	       Parameters:

	       1: a server category name
	       2: a valid disc_id

	       This will delete	the given entry	on the server (if you have permission).
	       Check the docs for the read() method to get more	information on the parameters.

	       Sets $obj->error	on error.

       write($server_category_string, $disc_id,	$cddb_formatted_data)
	       Parameters:

	       1: a server category name
	       2: a valid disc_id
	       3: a properly formatted array of	lines from a cddb file

	       Returns true on success,	otherwise $obj->error will be set.

       discid($number_of_tracks, $track_1_offset, $track_2_offset, ...,
       $total_number_of_seconds_of_disc)
	       Parameters:

	       1: The total number of tracks of	the current disc
	       2: An array of the track	offsets	in seconds
	       3: The total number of seconds of the disc.

	       Returns a valid disc_id if found, otherwise $obj->error will be set.

       get($filename)
	       Parameters:

	       1: The filename to retrieve from	the server.

	       Returns a scalar	containing raw file contents. Returns $obj->error on error.

       log($number_of_lines_per_section, start_date, end_date, 'day',
       $number_of_days,	'get')
	       Parameters:

	       1: The number of	lines per section desired
	       2: (Optional) A date after which	statistics should be calculated	in the format of hh[mm[ss[MM[DD[[CC]YY]]]]]
	       3: (Optional) Must pass a start_date if passing this. A date after start	date at	which time statistics
		   to not be calculated	in the format of hh[mm[ss[MM[DD[[CC]YY]]]]]
	       4: (Optional) The string	'day' to indicate that statistics should be calcuated for today.
	       5: (Optional) A number of days to be calculated,	default	is 1
	       6: (Optional) The string	'get' which will cause the log data to be recorded on the server's machine.

	       NOTE: You must provide at least one of the optional options (2,3,4).
	       Sets $obj->error	on error.

       motd
	       Parameters:
		   None

	       Returns the message of the day as a string.
	       Sets $obj->error	on error.

       proto($desired_protocol_level)
	       Parameters: (Optional) The desired protocol level as a number.

	       When called with	NO parameters, will set	the current and	maximum	allowed	procotol levels,
	       when called with	a desired protocol level it will be set, $obj->errror will be set if an	error occurs.

	       Returns the currently selected protocol level.

       put($type, $file)
	       Parameters:

	       1: type is either sites or motd
	       2: based	on param 1, an array of	lines, either a	list of	mirror sites
		   or a	new message of the day

	       Assuming	you have permission to do so the server	content	will be	updated.
	       Sets $obj->error	on error.

       quit
	       Parameters:
		   None

	       Disconnects from	the server.

       sites()
	     Parameters:
	       None

	       sites() returns an array	reference of urls that can be used as
	       a new remote_host.

       stat
	       Parameters:
		   None

	       Returns undef on	error (and sets	$obj->error). Otherwise	returns	a hashref
		   where the keys/values are:

		   max proto =>	<current_level>
		       An integer representing the server's current operating protocol level.

		   gets	=> <yes	| no>
		       The maximum protocol level.

		   updates => <yes | no>
		       Whether or not the client is allowed to initiate	a database update.

		   posting => <yes | no>
		       Whether or not the client is allowed to post new	entries.

		   quotes => <yes | no>
		       Whether or not quoted arguments are enabled.

		   current users => <num_users>
		       The number of users currently connected to the server.

		   max users =>	<num_max_users>
		       The number of users that	can concurrently connect to the	server.

		   strip ext =>	<yes | no>
		       Whether or not extended data is stripped	by the server before presented to the user.

		   Database entries => <num_db_entries>
		       The total number	of entries in the database.

		   <category_name => <num_db_entries>
		       The total number	of entries in the database by category.

       update
	       Parameters:

	       None

	       Tells the server	to update the database (if you have permission).
	       Sets $obj->error	on error.

       validate($validating_string)
	       Parameters:

	       1: A string to be validated.

	       If you have permission, given a string the server will validate the string
	       as valid	for use	in a write call	or not.

	       Sets $obj->error	on error.

       ver
	       Parameters:

	       None

	       Returns a string	of the server's	version.

       whom
	       Parameters:

	       None

	       If you have permission, returns a list of usernames of all connected users.
	       Sets $obj->error	on error.

       get_local_disc_id
	     Parameters:
	       getdiscid($) takes the device you want to use.
	       Basically this means '/dev/cdrom' or whatever on	linux machines
	       but it's	an array index in the number of	cdrom drives on	windows
	       machines	starting at 0. (Sorry, I may change this at a later time).
	       So, if you have only 1 cdrom drive then getdiscid(0) would work fine.

	     getdiscid() returns the discid of the current disc	in the given drive.

	       NOTE: See BUGS

       get_local_disc_data
	     Parameters:
	       getdiscdata($) takes the	device you want	to use.	See getdiscid()
	       for full	description.

	     getdiscdata() returns a hash of the given disc data as you	would
	     require for a call	to query. The returns hash look	like:

	      {
		ID => 'd00b3d10',
		NUM_TRKS => '3',
		TRACKS => [
			    '150',
			    '18082',
			    '29172'
			  ],
		SECONDS	=> '2879'
	      }

	      NOTE: A different	return type/design may be developed.

BUGS
	       The current version of getdiscid() and getdiscdata()
	       on the Windows platform takes ANY string	in a single
	       cdrom configuration and works fine.  That is if you
	       only have 1 cdrom drive;	you can	pass in	ANY string
	       and it will still scan that cdrom drive and return
	       the correct data.  If you have more then	1 cdrom	drive
	       giving the correct drive	number will return in an
	       accurate	return.

Resources The current version of the CDDB Server Protocol can be found at:
       http://ftp.freedb.org/pub/freedb/latest/CDDBPROTO
AUTHOR David Shultz <dshultz@cpan.org> Peter Pentchev <roam@ringlet.net>
CREDITS	Jeremy D. Zawodny <jzawodn@users.sourceforge.net> Pete Jordon
       <ramtops@users.sourceforge.net>
COPYRIGHT Copyright (c)	2002, 2014 David Shultz. Copyright (c) 2005, 2006
       Peter Pentchev. All rights reserved. This program is free software; you
       can redistribute	it and/or modify if under the same terms as Perl
       itself.
perl v5.32.0			  2014-10-15			     FreeDB(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | Resources The current version of the CDDB Server Protocol can be found at: | CREDITS Jeremy D. Zawodny <jzawodn@users.sourceforge.net> Pete Jordon | COPYRIGHT Copyright (c) 2002, 2014 David Shultz. Copyright (c) 2005, 2006

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::FreeDB&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help