Net_CDDB
[ class tree: Net_CDDB ] [ index: Net_CDDB ] [ all elements ]

Class: Net_CDDB_Client

Source Location: /Net_CDDB-0.3.0/CDDB/Client.php

Class Overview

Net_CDDB
   |
   --Net_CDDB_Client

Class for communication with CDDB/FreeDB.org servers


Author(s):

Variables

Methods


Inherited Variables

Inherited Methods

Class: Net_CDDB

Net_CDDB::calculateDiscId()
Calculate a disc ID based on the track offsets and the disc length
Net_CDDB::debug()
Enables or disables debugging ( prints out all responses/requests )
Net_CDDB::_createProtocol()
Create a protocol instance of the given type with the given parameters
Net_CDDB::_debug()
Prints/logs debugging messages
Net_CDDB::_parseRecord()
Parse a CDDB style database record into an array
Net_CDDB::_parseResult()
Parse a result string returned by a CDDB query into an array

Class Details

[line 56]
Class for communication with CDDB/FreeDB.org servers
  • Author: Keith Palmer <Keith@UglySlug.com>
  • Todo: Look at CDDB submission (broken? ugly dsn for determining submit server?)


[ Top ]


Class Variables

$_backend =

[line 64]

CDDB protocol backend object
  • Access: protected

Type:   object


[ Top ]

$_buffer =

[line 104]

String buffer for calls to backend
  • Access: protected

Type:   string


[ Top ]

$_cdreader =

[line 72]

CD TOC reader backend object, reads TOC from a CD-ROM disc
  • Access: protected

Type:   array


[ Top ]

$_device =

[line 96]

Location of CD-ROM device ( /dev/acd0, etc. )
  • Access: protected

Type:   string


[ Top ]

$_email =

[line 120]

String email address to use for submitting CDDB records
  • Access: protected

Type:   string


[ Top ]

$_persist =

[line 80]

Connection should persist over multiple method calls or not (valid for HTTP only)
  • Access: protected

Type:   bool


[ Top ]

$_submit_server =

[line 112]

String server name for new submissions via HTTP
  • Access: protected

Type:   string


[ Top ]

$_sudo =

[line 88]

Whether or not to use sudo to access the CD-ROM device
  • Access: protected

Type:   bool


[ Top ]



Method Detail

__construct (Constructor)   [line 205]

Net_CDDB_Client __construct( [string $protocol = 'cddbp://freedb.org:8880'], [string $cdreader = 'cddiscid:///dev/acd0'], [array $option_params = array()])

Construct a new CDDB object using the given backend/connection parameters (PHP v5.x)

Create a new CDDB object which gives access to CDDB/FreeDB.org servers to allow a user to query the database for information about music CDs. You can use this class to submit discs to the FreeDB.org project or retrieve music CD information such as disc title, artist, track names, etc.

The class uses a driver architecture both for accessing CDDB servers and for reading the table of contents off a local CD-ROM drive so that new CDDB and CD-ROM access methods can be easily added in the future.

The class currently offers three different driver protocols to access this the CDDB/FreeDB.org database: CDDBP, HTTP, or the local Filesystem.

      • filesystem:// - Read data from a local FreeDB.org format CDDB database dump
      • mdb2.your_database_type_here:// - Read data from an SQL database
      The class also offers a few different drivers to read the table of contents from the audio-CD in your CD/DVD drive:
      • cddiscid:// - Use the Linux/UNIX 'cd-discid' binary
      • cdparanoia:// - Use the Linux/UNIX 'cdparanoia' binary
      • test:// - Testing class to make sure things work like they should
      You may optionally provide an array of options parameters and CD TOC reader parameters to the class which specify options. Here are the valid array keys for each protocol:

      For CDDBP:

      • persist (defaults to false, set to true to reuse connection for multiple CDDB queries)
      • sudo (defaults to false, set to true if you want to execute the callback binary using sudo)
      • submit_uri (defaults to /~cddb/submit.cgi)
      For HTTP:
      • sudo (defaults to false, set to true if you want to execute the callback binary using sudo)
      • submit_uri (defaults to /~cddb/submit.cgi)
      For Filesystem:
      • sudo (defaults to false, set to true if you want to execute the callback binary using sudo)
      • motd_file (defaults to 'motd.txt', the file to display if you send a 'motd' Message Of The Day CDDB command)
      For MDB2:
      • sudo (defaults to false, set to true if you want to execute the callback binary using sudo)
      1.  $params_cddbp = array(
      2.      'persist' => true,
      3.  );
      4.  
      5.  $cddb = new Net_CDDB_Client('cddbp://my_username@freedb.org:8880''cddiscid:///dev/acd0'$params_cddbp);
      6.  //$cddb = new Net_CDDB_Client('http://my_username@freedb.org:80/~cddb/cddb.cgi', 'cddiscid:///dev/acd0');
      7.  //$cddb = new Net_CDDB_Client('filesystem:///path/to/FreeDB_Database/', 'cddiscid:///dev/acd0');
      8.  //$cddb = new Net_CDDB_Client('mdb2.mysql://username:password@hostname/my_freedb_database', 'cddiscid:///dev/acd0');
      9.  
      10.  
      11.  print("\n\nSearching for the CD in the CD-ROM drive:\n");
      12.  $discs $cddb->searchDatabaseForCD();
      13.  print_r($discs);

      • Access: public
      • Todo: Net_CDDB::listSupportedProtocols()
      • Todo: Net_CDDB::listSupportedReaders()
      • Todo: Net_CDDB::addObserver()
      • Todo: Sudo to a specific user? (use user key of cdreader dsn?)

      Parameters:

      string   $protocol     A DSN string specifying the protocol and server to connect to (i.e.: cddbp://freedb.org:8880)
      string   $cdreader     A DSN string specifying which CD-ROM TOC reader to use (i.e.: cddiscid:///dev/acd0)
      array   $option_params     An array of options / connection parameters

      [ Top ]

      Net_CDDB_Client (Constructor)   [line 127]

      Net_CDDB_Client Net_CDDB_Client( [ $protocol = 'cddbp://freedb.org:8880'], [ $cdreader = 'cddiscid:///dev/acd0'], [ $option_params = array()])

      Construct a new Net_CDDB_Client object using the given backend/connection parameters (PHP v4.x)

      Parameters:

         $protocol     
         $cdreader     
         $option_params     

      [ Top ]

      calculateDiscId   [line 679]

      string calculateDiscId( array $track_offsets, int $length, [bool $query = false])

      Calculate a disc ID based on the track offsets and the disc length
      • Return: 8-character disc ID value

      Overrides Net_CDDB::calculateDiscId() (Calculate a disc ID based on the track offsets and the disc length)

      Parameters:

      array   $track_offsets     The offsets of the tracks on the CD
      int   $length     The total number of seconds for the disc
      bool   $query     

      [ Top ]

      calculateDiscIdForCD   [line 468]

      string calculateDiscIdForCD( [string $device = null])

      Calculate the 8-byte disc id from the CD-ROM drive

      Parameters:

      string   $device     

      [ Top ]

      calculateLengthForCD   [line 514]

      integer calculateLengthForCD( [string $device = null])

      Calculate the length in seconds of the disc in the CD-ROM drive
      • Access: public

      Parameters:

      string   $device     

      [ Top ]

      calculateTrackOffsetsForCD   [line 487]

      array calculateTrackOffsetsForCD( [string $device = null])

      Calculate the track offsets from the TOC of the disc in the CD-ROM drive
      • Access: public
      • See: Net_CDDB_Utilities::calculateDiscIdForCD()

      Parameters:

      string   $device     

      [ Top ]

      connect   [line 260]

      bool connect( )

      Establish connection to CDDB server

      You *do not* need to manually call this, the other public methods of this class will ensure a connection is established before querying the database on their own. This is provided as a convience method just in case someone needs it.

      • Access: public

      [ Top ]

      disconnect   [line 276]

      bool disconnect( )

      Disconnect from CDDB server
      • Access: public

      [ Top ]

      getCategories   [line 299]

      array getCategories( )

      Retrieve list of CDDB categories from CDDB server

      Although the list of CDDB categories might look suspiciously like a list of music genres, there is actually a distinction. The CDDB server protocol defines a few categories which every audio CD must fit into. Beyond that, each actual record has a free-form text field indicating a more specific music genre. For instance, a record for a 'Punk Rock' audio CD would belong in the 'Rock' category with a disc genre of 'Punk Rock'.

      • Access: public

      [ Top ]

      getDetails   [line 445]

      Net_CDDB_Disc getDetails( Net_CDDB_Disc $disc)

      Fill a CDDBDisc object with detailed information about the disc

      After searching the CDDB database for discs matching yours by discid and track offsets, you can use this function to get detailed information about one of the CDDBDisc objects. This function will fill and return the Net_CDDB_Disc object with information about track offsets, song titles, etc.

      • Access: public

      Parameters:

      Net_CDDB_Disc   $disc     

      [ Top ]

      getDetailsByDiscId   [line 394]

      Net_CDDB_Disc getDetailsByDiscId( $category, string $discid, [ $obj = true], string $genre)

      Get CD information by genre and disc id value

      Searches the CDDB database for a CD matching the given genre and discid and returns a Net_CDDB_Disc object containing information for that CD. Returns false if the disc was not found in the database or an error occurs.


      Parameters:

      string   $genre     
      string   $discid     
         $category     
         $obj     

      [ Top ]

      help   [line 845]

      string help( [string $cmd = ''], [string $subcmd = ''])

      Get protocol help from the CDDB server
      • Access: public

      Parameters:

      string   $cmd     
      string   $subcmd     

      [ Top ]

      motd   [line 859]

      string motd( )

      Get the message of the day from the CDDB server
      • Access: public

      [ Top ]

      searchDatabase   [line 579]

      Net_CDDB_Disc searchDatabase( array $track_offsets, integer $length, [ $obj = true])

      Search and return Net_CDDB_Disc objects for CDs matching given length/offsets
      • Access: public

      Parameters:

      array   $track_offsets     
      integer   $length     
         $obj     

      [ Top ]

      searchDatabaseForCD   [line 539]

      array searchDatabaseForCD( [string $device = null])

      Search and return Net_CDDB_Disc objects matching the disc in the CD-ROM drive
      • Access: public

      Parameters:

      string   $device     

      [ Top ]

      searchDatabaseWithRawQuery   [line 616]

      array searchDatabaseWithRawQuery( string $query, [ $obj = true])

      Utility method to search for CDDB discs using a raw 'cddb query ...' command

      This is provided as a utility method for anyone who might want to search the CDDB database with a raw CDDB query command. It returns an array of Net_CDDB_Disc objects which match the query.

      1.  // CDDB queries look like this:
      2.  // cddb query [discid] [num_tracks] [offset_1] [offset_2] ... [offset_n] [length]
      3.  // Replace [discid] with the 8-char discid, [num_tracks] with the number of tracks, [offset_*] with the track offsets, and [length] with the total length of the CD in seconds
      4.   $query "cddb query 50dd30f 15 150 21052 43715 58057 71430 92865 117600 131987 150625 163292 181490 195685 210197 233230 249257 3541";
      5.  print_r($cddbsearchDatabaseWithRawQuery($query));

      • Access: public

      Parameters:

      string   $query     
         $obj     

      [ Top ]

      sites   [line 954]

      array sites( )

      Get a list of CDDB mirrors
      • Access: public

      [ Top ]

      statistics   [line 873]

      array statistics( )

      Get CDDB database server statistics
      • Access: public

      [ Top ]

      submitDisc   [line 723]

      bool submitDisc( Net_CDDB_Disc $obj, [string $email = null], [bool $test = false])

      Submit a revised/new Net_CDDB_Disc object to the FreeDB.org database

      Note that at this time only submission via HTTP is supported. The only other option is SMTP, which may be supported in the future. This method uses the HTTP_Request class to make the request. I chose to include the HTTP_Request class here instead of globally because most users will use the Net_CDDB package for read-only access to CDDB servers, and thus won't be using this method.

      • Access: public
      • Uses: HTTP_Request

      Parameters:

      Net_CDDB_Disc   $obj     A Net_CDDB_Disc object containing CD information
      string   $email     
      bool   $test     Whether or not this should be a test submission

      [ Top ]

      version   [line 984]

      string version( )

      Get the CDDB server version string
      • Access: public

      [ Top ]

      _createReader   [line 819]

      object _createReader( string $type, array $params)

      Create a cd reader instance of a given type with the parameters

      Parameters:

      string   $type     
      array   $params     

      [ Top ]

      _readLine   [line 357]

      string _readLine( )

      Read a line from the response buffer
      • Access: protected

      [ Top ]

      _readResponseStatus   [line 345]

      int _readResponseStatus( )

      Reads the return status for the last command ( 200, 210, 500, etc. )
      • Access: protected

      [ Top ]

      _send   [line 326]

      void _send( string $query)

      Send a query to the backend and retrieve the result from the query
      • Access: protected

      Parameters:

      string   $query     The command string to send

      [ Top ]


      Documentation generated on Sun, 25 Feb 2007 14:00:13 -0500 by phpDocumentor 1.3.0. PEAR Logo Copyright © PHP Group 2004.