.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::DAAP::Client 3"
.TH Net::DAAP::Client 3 "2008-01-02" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
.Vb 1
\&  Net::DAAP::Client - client for Apple iTunes DAAP service
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  my $daap;  # see WARNING below
\&  $daap = Net::DAAP::Client->new(SERVER_HOST => $hostname,
\&                                 SERVER_PORT => $portnum,
\&                                 PASSWORD    => $password);
\&  $dsn = $daap->connect;
.Ve
.PP
.Vb 3
\&  $dbs_hash = $daap->databases;
\&  $current_db = $daap->db;
\&  $daap_db($new_db_id);
.Ve
.PP
.Vb 3
\&  $songs_hash = $daap->songs;
\&  $playlists_hash = $daap->playlists;
\&  $array_of_songs_in_playlist = $daap->playlist($playlist_id);
.Ve
.PP
.Vb 1
\&  $url = $daap->url($song_or_playlist_id);
.Ve
.PP
.Vb 4
\&  $binary_audio_data = $obj->get($song_id);
\&  $binary_audio_data = $obj->get(@song_ids);
\&  $song_id = $obj->save($dir, $song_id);
\&  @song_ids = $obj->get($dir, @song_ids);
.Ve
.PP
.Vb 1
\&  $daap->disconnect;
.Ve
.PP
.Vb 3
\&  if ($daap->error) {
\&      warn $daap->error;  # returns error string
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::DAAP::Client provides objects representing connections to \s-1DAAP\s0
servers.  You can fetch databases, playlists, and songs.  This module
was written based on a reverse engineering of Apple's iTunes 4 sharing
implementation.  As a result, features that iTunes 4 doesn't support
(browsing, searching) aren't supported here.
.PP
Each connection object has a destructor, so that you can forget to
\&\f(CW\*(C`disconnect\*(C'\fR without leaving the server expecting you to call back.
.Sh "\s-1WARNING\s0"
.IX Subsection "WARNING"
If you store your object in a global variable, Perl can't seem to
disconnect gracefully from the server.  Until I figure out why, always
store your object in a lexical (\f(CW\*(C`my\*(C'\fR) variable.
.SH "METHODS"
.IX Header "METHODS"
.Sh "* \fInew()\fP"
.IX Subsection "* new()"
.Vb 1
\&    $obj = Net::DAAP::Client->new(OPTNAME => $value, ...);
.Ve
.PP
The allowed options are:
.IP "\s-1SERVER_NAME\s0" 4
.IX Item "SERVER_NAME"
The hostname or \s-1IP\s0 address of the server.
.IP "\s-1SERVER_PORT\s0" 4
.IX Item "SERVER_PORT"
The port number of the server.
.IP "\s-1PASSWORD\s0" 4
.IX Item "PASSWORD"
The password to use when authenticating.
.IP "\s-1DEBUG\s0" 4
.IX Item "DEBUG"
Print some debugging output
.IP "\s-1SONG_ATTRIBUTES\s0" 4
.IX Item "SONG_ATTRIBUTES"
The attributes to retrieve for a song as an array reference.  The
default list is:
.Sp
.Vb 2
\& [qw( dmap.itemid dmap.itemname dmap.persistentid daap.songalbum
\&      daap.songartist daap.songformat daap.songsize )]
.Ve
.Sh "* \fIconnect()\fP"
.IX Subsection "* connect()"
.Vb 2
\&    $name = $obj->connect
\&        or die $obj->error;
.Ve
.PP
Attempts to fetch the server information, log in, and learn the latest
revision number.  It returns the name of the server we've connected to
(as that server reported it).  It returns \f(CW\*(C`undef\*(C'\fR if any of the steps
fail.  If it fails fetching the revision number, it logs out before
returning \f(CW\*(C`undef\*(C'\fR.
.Sh "* \fIdatabases()\fP"
.IX Subsection "* databases()"
.Vb 1
\&    $dbs = $self->databases();
.Ve
.PP
Returns a hash reference.  Sample:
.Sh "* \fIdb()\fP"
.IX Subsection "* db()"
.Vb 2
\&    $db_id = $obj->db;     # learn current database ID
\&    $obj->db($db_id);      # set current database
.Ve
.PP
A database \s-1ID\s0 is a key from the hash returned by
\&\f(CW\*(C`$obj\->databases\*(C'\fR.
.PP
Setting the database loads the playlists and song list for that
database.  This can take some time if there are a lot of songs in
either list.
.PP
This method returns true if an error occurred, false otherwise.
If an error occurs, you can't rely on the song list or play list
having been loaded.
.Sh "* \fIsongs()\fP"
.IX Subsection "* songs()"
.Vb 1
\&    $songs = $obj->songs();
.Ve
.PP
Returns a hash reference.  Keys are song IDs, values are hashes with
information on the song.  Information fetched is specified by
\&\s-1SONG_ATTRIBUTES\s0, the default set is:
.IP "dmap.itemid" 4
.IX Item "dmap.itemid"
Unique \s-1ID\s0 for the song.
.IP "dmap.itemname" 4
.IX Item "dmap.itemname"
Title of the track.
.IP "dmap.persistentid" 4
.IX Item "dmap.persistentid"
\&\s-1XXX\s0 [add useful explanation here]
.IP "daap.songalbum" 4
.IX Item "daap.songalbum"
Album name that the track came from.
.IP "daap.songartist" 4
.IX Item "daap.songartist"
Artist who recorded the track.
.IP "daap.songformat" 4
.IX Item "daap.songformat"
A string, \*(L"mp3\*(R", \*(L"aiff\*(R", etc.
.IP "daap.songsize" 4
.IX Item "daap.songsize"
Size in bytes of the file.
.PP
A sample record:
.PP
.Vb 9
\&    '127' => {
\&        'daap.songsize' => 2597221,
\&        'daap.songalbum' => 'Live (Disc 2)',
\&        'dmap.persistentid' => '4081440092921832180',
\&        'dmap.itemname' => 'Down To The River To Pray',
\&        'daap.songartist' => 'Alison Krauss + Union Station',
\&        'dmap.itemid' => 127,
\&        'daap.songformat' => 'mp3'
\&        },
.Ve
.PP
To find out what other attributes you can request consult the \s-1DAAP\s0
spec at http://tapjam.net/daap/draft.html
.Sh "* \fIplaylists()\fP"
.IX Subsection "* playlists()"
.Vb 1
\&    $songlist = $obj->playlists();
.Ve
.PP
Returns a hash reference.  Keys are playlist IDs, values are hashes
with information on the playlist.
.PP
\&\s-1XXX:\s0 explain keys
.PP
A sample record:
.PP
.Vb 7
\&    '2583' => {
\&        'dmap.itemcount' => 335,
\&        'dmap.persistentid' => '4609413108325671202',
\&        'dmap.itemname' => 'Recently Played',
\&        'com.apple.itunes.smart-playlist' => 0,
\&        'dmap.itemid' => 2583
\&    }
.Ve
.Sh "* playlist"
.IX Subsection "* playlist"
.Vb 1
\&    $playlist = $obj->playlist($playlist_id);
.Ve
.PP
A playlist \s-1ID\s0 is a key from the hash returned from the \f(CW\*(C`playlists\*(C'\fR
method.  Returns an array of song records.
.Sh "* url"
.IX Subsection "* url"
.Vb 2
\&    $url = $obj->url($song_id);
\&    $url = $obj->url($playlist_id);
.Ve
.PP
Returns the persistent \s-1URL\s0 for the track or playlist.
.Sh "* get"
.IX Subsection "* get"
.Vb 1
\&    @tracks = $obj->get(@song_ids);
.Ve
.PP
Returns the binary data of the song.  A song \s-1ID\s0 is a key from
the hash returned by \f(CW\*(C`songs\*(C'\fR, or the \f(CW\*(C`dmap.itemid\*(C'\fR from one of
the elements in the array returned by \f(CW\*(C`playlist\*(C'\fR.
.Sh "* save"
.IX Subsection "* save"
.Vb 1
\&    $tracks_saved = $obj->save($dir, @song_ids);
.Ve
.PP
Saves the binary data of the song to the directory.  Returns the
number of songs saved.
.Sh "* \fIdisconnect()\fP"
.IX Subsection "* disconnect()"
.Vb 1
\&    $obj->disconnect;
.Ve
.PP
Logs out of the database.  Returns \f(CW\*(C`undef\*(C'\fR if an error occurred, a
true value otherwise.  If an error does occur, there's probably not
much you can do about it.
.Sh "* \fIerror()\fP"
.IX Subsection "* error()"
.Vb 1
\&    $string = $obj->error;
.Ve
.PP
Returns the most recent error code.  Empty string if no error occurred.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
No authentication.  No updates.  No browsing.  No searching.
.SH "AUTHOR"
.IX Header "AUTHOR"
Nathan Torkington, <nathan \s-1AT\s0 torkington.com>.  For support, join the
\&\s-1DAAP\s0 developers mailing list by sending mail to <daap\-dev\-subscribe
\&\s-1AT\s0 develooper.com>.  See the \s-1AUTHORS\s0 file in the distribution for other
contributors.
.PP
Richard Clamp <richardc@unixbeard.net> took on maintainership duties
for the 0.4 and subsequent releases.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DAAP::DMAP